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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered and the description only adds the external-source framing. It says nothing about whether duplicate alerts are deduplicated, whether the alert can be resolved later, or what the caller gets back on success.

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 front-loaded sentence that states the action and scope with no filler. It is efficient, though it is arguably too thin given the nested body it fronts.

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

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

For a write tool with a nested request body and no output schema, the description covers the what but not the outcome — no indication of what ID or object is returned, whether severity defaults apply, or whether ClientId must already exist. Annotations absorb some of the burden, leaving it adequate but with 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 100% and the nested body fields (Name, ClientId, Resource, Severity enum, Description) are documented in the schema, so the baseline of 3 applies. The description adds no parameter-level guidance of its own, and notably does not compensate for the garbled Resource description ('g. host name, service).').

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 ('Raises') and resource ('a new alert') scoped to a client in Gorelo, which cleanly separates it from the sibling list_alerts reader. It does not name the sibling explicitly, 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?

The phrase 'such as an alert from an outside monitoring tool' implies the intended ingestion scenario, giving the agent a usable context cue. There is no explicit when-not guidance, no mention of how this relates to gorelo_list_alerts, and no note about creating tickets instead.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds one genuinely new behavioral fact — that a default location is created as a side effect — but says nothing about what happens on duplicate names/domains, required auth scope, or what the response returns.

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

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

A single short sentence with zero filler, and the parenthetical side-effect is front-loaded before any other consideration. Nothing to trim.

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

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

Given a rich, fully-described nested schema and annotations that cover the safety profile, the description is close to sufficient. However, for a creation tool with no output schema it omits what is returned (e.g. the new client ID) and any failure/duplicate conditions, which an agent would want before invoking.

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

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

Schema description coverage is 100% and the nested Location object is thoroughly documented with per-field max lengths, so the schema carries nearly all parameter meaning. The description's only added value is clarifying that the Location object represents the client's default location, not an additional one.

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 gives a specific verb+resource ("Creates a client") and adds a meaningful scope detail: a default location is created alongside it. That distinguishes it clearly from read/update siblings like gorelo_get_client and gorelo_update_client, though it never explicitly contrasts with gorelo_list_clients or other create tools.

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

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

There is no guidance on when to use this tool versus alternatives (e.g. creating a client with locations separately via gorelo_list_client_locations), and no stated prerequisites, permissions, or duplicate-handling rules. Usage must be inferred 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?

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description must add value, and it does by disclosing the 'temporary contact' fallback when no client is supplied. It does not cover failure modes (duplicate emails), permission requirements, or what is returned on success.

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 sentence with zero filler, front-loading the primary behavior and appending the branching condition immediately after.

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 mutation with a deeply nested body and no output schema, the description covers the core branching but leaves an agent guessing about the response payload (e.g. created contact ID) and about validation behavior. Adequate but not thorough.

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 each body field is fully documented, so baseline is 3. The description goes one step further by explaining the semantic consequence of omitting the optional ClientId (creates a temporary contact), which the schema itself does not state.

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 (creates) and resource (contact) plus the scope variant 'under a client, or temporary'. This naturally separates it from gorelo_update_contact and gorelo_get_contact, though it never names a 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?

The client/no-client branch is an implicit usage condition, telling the agent which mode to pick based on whether a ClientId exists. There is no explicit guidance about when to prefer create vs update, or prerequisites such as required permissions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds the domain semantics of a custom asset and the hardware-type lookup dependency, but says nothing about what is returned (no output schema exists) or about failure conditions such as an inactive client or location.

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, zero filler, with the core definition front-loaded and the prerequisite lookup placed second. Every sentence earns its place.

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

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

For a mutation tool with a single nested body object fully described in the schema, the description covers purpose, the domain definition, and the one external dependency. With no output schema, a note on what the call returns (e.g., the created asset identifier) 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 coverage is 100%, so every body field (Name, ClientId, ContactId, LocationId, HardwareTypeId, warranty date, etc.) is already documented in the schema. The description's only parameter-relevant contribution is the pointer to the hardware-types listing tool; the baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Creates a custom asset') and then defines the term, disambiguating it from ordinary assets: 'a device without the Gorelo agent, such as a printer or firewall.' The concrete examples make it clear how this differs from sibling asset tools like gorelo_list_assets or gorelo_get_custom_asset.

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_custom_asset_hardware_types to obtain a valid HardwareTypeId, which is real prerequisite guidance. It does not, however, say when NOT to use this (e.g., when the device can run the agent) or contrast with gorelo_update_custom_asset for edits.

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 declare readOnlyHint=false and destructiveHint=false, so the write-but-safe profile is already conveyed. The description adds the HTML-body nature of the write and the nesting relationship, but says nothing about permissions, side effects, or what a created document returns. Some added context, 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?

A single efficient sentence with the verb and key scope constraints front-loaded. No wasted text, though it is quite terse for a create tool.

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

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

With a fully documented nested parameter and annotations covering the mutation profile, the description covers what an agent needs to call it. Only minor gaps remain (permissions, return shape), and no output schema exists to cover the latter.

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%: the nested object documents Body (HTML, no data: URLs), Title (max 200), ClientId, and ParentDocumentId in detail. The description only echoes these at a high level and adds no syntax or formatting detail beyond the schema, 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 ('Creates a document') and adds meaningful scope: HTML body, client vs internal, optional nesting. An agent can distinguish it from gorelo_update_document and gorelo_duplicate_document, though it never names a 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?

Implies the create context (new document, client or internal, nested or top-level) but gives no explicit when-to-use vs alternatives or prerequisites. The 'either for a client or for internal use' clause clarifies intent somewhat, but routing between create/update/duplicate is left to inference.

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

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

Annotations already declare a non-destructive mutation, but the description adds nothing beyond that: no permissions required, no side effects, and no mention of the skip-if-already-linked behavior that lives only in the nested schema. The description carries little behavioral value on its own.

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 front-loaded sentence with no filler. It is efficiently sized, though the lack of any usage or behavioral notes means the structure has no layers beyond the one-line purpose.

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 rich schema and annotations declaring a safe mutation, the description is minimally adequate. It could still say more about the link operation's effect and idempotency (already linked records are skipped), which matters for a create tool with nested payload and no output schema.

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

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

Schema description coverage is effectively 100%, with ItemTypeId mappings, ItemId formats, the 1-100 limit, and skip behavior all documented in the schema. The description adds no parameter meaning beyond repeating the tool purpose, 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?

States a specific verb-resource pair: it relates a document to other records, which is distinct from sibling read tools like gorelo_list_document_related_items. However, it never explicitly names that alternative or clarifies that this creates links rather than updates existing ones.

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 prerequisites, and no mention of alternatives such as listing existing related items first. The agent must infer the call context entirely 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is known. The description adds that the output is a shareable fill-and-submit link, which is useful, but omits whether the link expires, is single-use, or requires auth — meaningful traits for a link-issuing mutation.

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 clean sentence with the core purpose front-loaded and no filler. It is arguably under-specified rather than padded, so brevity is a virtue here rather than a flaw in structure.

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 mutation tool with a nested body object and no output schema, the description should at least say what comes back (a URL?) and how TaskId versus TicketId scoping affects the generated link. Neither is covered, leaving the agent to infer the result shape entirely.

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 documents formId, TaskId, and TicketId including their mutual exclusivity. The description adds nothing about parameters, so the baseline 3 applies — the schema carries all the weight.

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 (creates) and resource (a link for filling in and submitting a form), which is clearly distinct from every sibling tool listed. It stops short of naming which workflow or related endpoint it pairs with, but an agent can identify the operation immediately.

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 says what the tool does but gives no guidance on when to reach for it versus alternatives such as gorelo_list_form_responses or gorelo_list_forms. There are no prerequisites, no exclusions, and no mention of how TaskId/TicketId scoping should drive the choice.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered by structured data. The description contributes nothing beyond that — no mention of permission requirements, validation failures on missing client/group IDs, or side effects such as watcher/lead assignment rules.

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 single short sentence has zero waste and is front-loaded, but it errs toward under-specification rather than conciseness — it conveys no structure for a tool whose payload is a 13-field nested object.

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 create tool with a required nested body object and no output schema, the description should say what comes back and how required foreign keys are sourced. Neither is addressed; the description is effectively one restated name against a rich 100%-documented 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%, and the nested body documents all 13 properties including backdating fields and the SharedWithContactIds constraint. The description adds no parameter meaning, so the 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 ("Creates a project"), so the agent knows the operation. However, it adds essentially nothing beyond the tool name gorelo_create_project, and does not distinguish it from siblings such as gorelo_update_project, gorelo_list_projects, or gorelo_create_project_section.

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 use this tool versus alternatives, no prerequisites (e.g. needing valid ClientId/GroupId/LocationId/TypeId values), and no mention of related lookup tools like gorelo_list_clients or gorelo_list_project_types that would supply those identifiers.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered structurally. The description adds nothing beyond that: it does not mention that the body must be HTML, that attachments must be uploaded first, or what happens if ConversationId is omitted. With the bar lowered by annotations, this still adds no value.

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

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

A single front-loaded sentence with zero waste. It is efficient, but the brevity is closer to under-specification than to disciplined conciseness for a tool with a nested request body.

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?

This is a write tool with a nested body object containing optional author/date/conversation/attachment fields and no output schema. The description says nothing about the two-step attachment flow, HTML formatting requirement, or the effects of posting, leaving the description thinner than the tool's complexity warrants.

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

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

Schema description coverage is 100%, including detailed nested field docs (HTML body, UTC CreatedOn, attachment upload flow, conversation type enum-ish values). The description contributes nothing beyond the schema, 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 ('Posts a comment on a project'), which is enough to separate it from the sibling comment tools that target tasks and tickets. It never names those siblings explicitly, so differentiation is inferred from the word 'project' 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?

There is no guidance on when to use this versus gorelo_create_project_task_comment, gorelo_create_ticket_comment, or gorelo_list_project_comments. No prerequisites, permissions, or context for posting are given; the agent must infer everything 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that—no mention of default color behavior, whether the section is appended or ordered, or what happens on duplicate titles. With annotations present the bar is lower, but this text contributes no behavioral 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?

A single front-loaded sentence with zero waste. However, its brevity borders on under-specification, leaving no room for the routing or behavioral context an agent would benefit from.

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 schema fully documents both parameters including the nested body, and annotations cover the mutation/safety profile, so the core invocation is inferable. Still, for a create tool in a dense sibling set, the description should do more to distinguish it and mention prerequisites.

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 nested body fields (Title, Color with default #56A0F9, CreatedByName) fully documented in the schema itself. The description adds no parameter meaning, 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?

The description states a specific verb ('Adds') and resource ('a section to a project'), which clearly separates it from siblings like gorelo_update_project_section and gorelo_list_project_sections. It stops short of explicitly naming those alternatives, but the purpose is unambiguous.

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

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

There is no guidance on when to use this tool versus gorelo_update_project_section or gorelo_create_project, no prerequisites (such as needing an existing projectId), and no exclusions. The agent must infer usage entirely from the name and schema.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, covering the mutation/safety profile. The description adds essentially nothing beyond that – no mention of required section nesting, side effects, permissions, or what a successful creation returns, all of which would be valuable beyond the annotations.

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

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

A single efficient sentence that is front-loaded with the action and target. It is appropriately short, though terse given the rich nested body the tool actually accepts.

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 mutation tool with a nested, multi-field body and no output schema, the description relies heavily on the schema (which is complete) and annotations for safety. The main gaps – when to use it and behavioral/return context – are only partially covered.

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

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

Schema description coverage is 100%, so all parameters (Title, SectionId, StatusId, PriorityId, etc.) are fully documented in the nested schema. The description adds no parameter meaning 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 ('Creates') and resource ('a task on a project's board'), which lets an agent distinguish this from sibling operations like create_project, create_ticket, or create_project_section. It's clear but doesn't explicitly route against the near-neighbor create_ticket.

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 offers no when-to-use guidance, prerequisites, or alternatives. With many create_* siblings (create_ticket, create_project_section, create_project_task_approval), nothing tells the agent when this tool is the right choice versus those.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive profile is covered. The description adds one genuinely useful behavioral fact beyond them — that this reaches out to contacts, implying notifications are dispatched — but says nothing about what an approval record looks like, whether duplicates are permitted, or what is returned.

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

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

A single front-loaded sentence with no filler. It is efficiently sized, though the brevity borders on under-specification rather than true concision.

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 mutation with a nested body object, two annotations, and no output schema, the description leaves the agent guessing about side effects (notifications), return value, and duplicate handling. The fully documented schema keeps this at minimum-viable rather than inadequate.

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

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

Schema description coverage is 100%, including the nested body and its Name and ContactIds fields, so the schema carries the parameter burden. The description contributes nothing extra — it does not clarify the relationship between projectId and taskId or what 'Name' is displayed as.

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 concrete action (asking contacts to approve something) and the resource it lives on (a task), so an agent can tell it creates an approval request rather than reading one. It does not, however, distinguish itself from the near-identical sibling gorelo_create_ticket_approval, which the name alone would have to carry.

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 versus gorelo_create_ticket_approval or gorelo_get_project_task_approval, no prerequisites, and no note that the task must already exist in the given project. The agent must infer all routing 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?

Annotations already declare this is a non-read-only, non-destructive write. The description adds nothing beyond that – it doesn't explain that attachments must be uploaded first, that CreatedOn is for history imports only, or that leaving CreatedByName blank records 'API', all of which are buried in schema descriptions rather than surfaced as behavior.

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

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

A single front-loaded sentence with zero waste. Its brevity is not padded, though it slides into under-specification rather than earning the sentence.

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

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

For a nested-body mutation tool with no output schema, the description omits what a caller most needs: whether responses return the created comment, the attachment upload prerequisite, and how ConversationId/ConversationTypeId change the target of the post.

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

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

Schema description coverage is 100% and the nested body parameters carry detailed descriptions, so the schema does the heavy lifting. The description adds no parameter meaning of its own, which is the baseline-3 case.

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 ('Posts a comment on a task'), so the agent knows exactly what the tool does. It does not explicitly distinguish itself from project-level or ticket comment siblings, which would have earned 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 guidance on when to use this versus gorelo_create_project_comment, gorelo_create_ticket_comment, or the side-conversation tools, and no prerequisites (task must exist, permissions, conversation targeting) are mentioned.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is covered structurally. However, the description adds nothing beyond that: it does not disclose that the operation involves outbound communication to external parties (the body requires a Name/Email of an outside person plus CcEmails), nor any permission or notification consequences of starting such a thread.

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 front-loaded sentence with zero filler, so there is no wasted text. The tradeoff is that its brevity comes from under-specification rather than efficient density — nothing beyond the bare action is stated.

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 mutation tool with a nested request body, no output schema, and external-recipient semantics, the description is too thin. An agent still lacks the information that this initiates outbound email to a third party and what occurs on the task once the conversation starts.

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

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

Schema description coverage is 100%, and the nested body object documents Name, Email, and CcEmails individually, so the schema carries the parameter burden. The description contributes no additional semantics about the projectId/taskId scoping or how the recipient is chosen, which is acceptable at baseline but adds no value.

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

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

The description names a specific verb ("Starts") and resource ("a side conversation on a task"), which is clear enough for an agent to know it creates a new conversation thread rather than listing one. It does not differentiate from the close sibling gorelo_create_ticket_side_conversation, but the tool name's project/task scoping and the schema make the distinction recoverable.

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 use this versus gorelo_create_project_task_comment, gorelo_list_project_task_conversations, or the ticket-side-conversation variant. The only signal is the implied "create a thread" reading of the verb, leaving the agent to infer the use case.

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 this is a non-read-only, non-destructive mutation, so the safety profile is covered. Beyond that the description adds nothing: it does not mention that the call sends a 'ticket created' email when SendTicketCreatedEmail is set, that CreatedOn/ClosedOn permit backdating imports, or that referenced IDs must already exist. For a create operation with many side-effect-capable fields, this leaves real behavioral gaps unflagged.

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 single sentence is front-loaded and contains no filler, so it is not bloated. But it is under-specified rather than concise — the brevity comes at the cost of any useful content.

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

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

The payload is a nested body object with roughly 23 fields, four of them required, and there is no output schema to explain what is returned. For a mutation of this complexity, a bare one-liner leaves the agent without any information about the returned identifier, preconditions, or validation constraints that the schema alone doesn't convey contextually.

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 nested field (Title, StatusId, GroupId, TypeId, backdating fields, email flag) is already documented in the schema. The description contributes no additional parameter meaning, which is the expected baseline 3 when the schema does all the work.

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 clear verb (creates) and resource (a ticket in Gorelo), so the basic action is unambiguous. However, it does nothing to distinguish this from ticket-adjacent siblings such as gorelo_create_ticket_comment, gorelo_create_ticket_approval, or gorelo_create_ticket_side_conversation, and says nothing about scope or what a created ticket contains.

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 when-to-use guidance, no prerequisites (e.g. needing valid GroupId/StatusId/TypeId values first via gorelo_list_ticket_statuses and gorelo_list_groups), and no mention of alternatives such as gorelo_update_ticket. The agent must infer all routing from the tool name alone.

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 declare readOnlyHint=false and destructiveHint=false, consistent with a creation tool. The description adds one genuinely useful behavioral fact beyond the annotations — every listed contact starts in Pending status — but omits whether contacts are notified, whether the approval can be edited afterward, and what permissions are required.

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, the core action front-loaded and the one non-obvious behavioral fact immediately after. 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?

It is a mutation tool with a nested body object and no output schema, yet the description never indicates what is returned (an approval identifier?) or what the caller should do next. Adequate to invoke, thin for a complex create operation.

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

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

Schema description coverage is 100%, so both ticketId and the nested body fields are already documented. The sentence about contacts starting Pending adds a small amount of meaning to ContactIds, but no syntax, ordering, or limit details beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Creates an approval on a ticket"), which immediately separates it from gorelo_create_project_task_approval. It does not explicitly name that sibling or say how the two differ, 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?

There is no guidance on when to use this versus gorelo_create_project_task_approval, no preconditions (ticket must exist, contacts must be valid), and no statement about what happens if an approval already exists. The agent must infer all of this.

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 declare this is a non-read-only, non-destructive mutation. The description adds useful behavioral context beyond annotations: the comment is shown as posted by the API rather than the user, and To/Cc are derived from the ticket's conversation.

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 short sentences, front-loaded with the core action and followed by important behavioral details. Every sentence adds value with no filler.

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

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

For a mutation tool with a nested schema and no output schema, the description covers the core action, author identity, and recipient behavior. However, it omits return-value expectations, side effects such as notifications, and when to prefer this tool over sibling creation tools.

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

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

Schema description coverage is 100%, so parameter semantics are already well documented in the schema. The description's note about To/Cc coming from the conversation adds minor context but does not meaningfully elaborate on the nested parameters like Attachments, CreatedOn, or CreatedByName.

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 a specific verb and resource: 'Adds a comment to a ticket.' However, it does not distinguish this tool from sibling tools like gorelo_create_ticket_side_conversation or gorelo_create_ticket_approval.

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

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

The description implies the tool is used to add comments, but it gives no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as side conversations or approvals, which are present as sibling tools.

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

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

The annotations already state that this is a non-read-only, non-destructive mutation, and the description adds real value: it reveals that a side conversation must be followed by a comment posted with conversationType=3, which is workflow context the annotations lack. It still omits side effects such as sending email to the Email and CcEmails recipients, and whether the operation can be undone. That is enough for a 3, but no higher.

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 front-loaded sentences with no filler. The sentence about how to follow up is well placed as a next step, though technically it describes a different tool rather than this one. That is minor and still earns a 4.

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?

This is a two-parameter mutation with full schema coverage, annotations, and no output schema, and the description states the key response field: the returned Id. An agent knows what to call and what to do next. The only remaining gap is that it says nothing about recipient notification side effects or failure modes.

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

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

Schema description coverage is 100%, and the nested body object documents Name, Email, CcEmails, and AttachPublicConversation, so the schema already carries the meaning of each parameter. The description adds nothing about the parameters in its own schema; instead, it documents conversationId and conversationType=3, which belong to a follow-up call. The baseline of 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?

The description names a specific verb and resource: 'Creates a side conversation on a ticket.' That is unambiguous and, combined with the follow-up sentence about posting a comment into it, distinguishes this from gorelo_create_ticket_comment. It never explicitly says how it differs from the sibling list_ticket_conversations or create_project_task_side_conversation, though, so a 4 fits better than 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?

The second sentence gives useful workflow guidance: call this first, then reuse the returned Id as conversationId with conversationType=3. However, it never states when to create a side conversation instead of a plain ticket comment, or what preconditions apply (for example, whether the ticket must be in a certain state). The intended usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds nothing beyond that — no mention of validation failures (404 on unknown task/ticket), no side effects on billing or approvals, no note about what is returned.

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

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

A single terse sentence with zero waste, but it is undersized rather than appropriately sized — brevity here comes at the cost of missing information rather than from disciplined editing.

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 nested 13-field mutation with no output schema, the description is thin, but the very rich schema carries most of the load. An agent could call it correctly from the schema alone, though it would learn nothing about outcomes or error behavior from the description.

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

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

Schema description coverage is 100%, including the ticket/task exclusivity rule, enum values for BillableStatusId, and the 5000-character attachment limit, so baseline 3 applies. The description adds no parameter meaning of its own and its 'against a ticket' phrasing slightly conflicts with the documented TaskId alternative.

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 ('Logs time'), which distinguishes it from the list/get/update time-entry siblings. However, 'against a ticket' undersells the schema's TicketId-or-TaskId design, so the scope isn't fully accurate.

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 use this rather than gorelo_update_time_entry or gorelo_list_time_entries, and no mention of prerequisites such as needing a valid ticket/task, user, or work type. The agent must infer all usage context from the schema.

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 that this is a non-read-only, non-destructive operation, so the safety profile is covered. The description adds that checks run on a schedule and support ICMP, HTTP, and TCP targets, but it does not discuss side effects such as AdoptClientAssets or permission requirements.

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

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

It is a single well-formed sentence with the core operation and supported check types front-loaded. There is no unnecessary wording.

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

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

For a creation tool with a nested request body, the description covers the core purpose but leaves out when to use it, prerequisites like the client/location pairing noted in the schema, and side-effect context. The rich schema and existing annotations fill much of the gap, but the description alone is only minimally complete.

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

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

Schema description coverage is 100%, so the detailed field descriptions already carry parameter meaning. The description's mention of host, web address, and TCP port loosely maps to Target fields but adds no syntax, constraints, or required-field 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 uses a specific verb ('Creates') and resource ('uptime check') and explains the check types: ping a host, request a web address, or connect to a TCP port on a schedule. It is clear against the list/get/update siblings by name and operation, but it does not explicitly distinguish itself from 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 description states what the tool does but gives no guidance on when to use it versus viewing, updating, or listing uptime checks. There are no prerequisites, exclusions, or named alternatives.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, which is already the baseline for a create-style operation. The description adds nothing about what a duplicate carries over (versions, related items, comments, attachments), whether the copy is fully independent, or what happens if the source doesn't exist — behaviorally important for a duplication 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?

A single front-loaded sentence with no filler, and the key outcome (a new document) is stated immediately. It is under-specified rather than padded, so conciseness itself is fine.

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 duplication mutation with a nested body object and no output schema, the description leaves the important questions unanswered: what the copy includes, whether the duplication is idempotent/repeatable, and what identifying information the response returns for the new document. The only detail an agent gets — where the title comes from — lives in the schema, not the description.

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%: the schema documents documentId ("Document to duplicate") and the nested body.Title with its 200-char limit and " clone" default behavior. The description adds no parameter detail beyond that, so the baseline 3 applies since the schema does all the work.

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 ("Makes a copy of a document") and clarifies the result is a new document, so it's clearly distinct from gorelo_get_document or gorelo_update_document. It doesn't explicitly differentiate from the sibling gorelo_create_document, which is the main confusion risk for a duplicate operation.

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 duplicate versus calling gorelo_create_document from scratch, no prerequisites (permissions needed on the source document), and no exclusions. The agent must infer the selection criteria from the tool name alone.

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 description is not the sole carrier of behavior. It adds nothing about not-found behavior, id format expectations, or whether the response includes related hardware/assignment data, which would have earned a higher score.

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 short sentence, front-loaded with the verb and resource, with zero filler. Nothing could be removed without losing meaning.

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 getter with 100% schema coverage and no output schema, the description covers what is needed to call it correctly. Only minor gaps (what distinguishes an agent asset from custom assets, not-found behavior) remain.

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

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

The single parameter is fully documented in the schema ('Device identifier'), so the description need not repeat it. It also doesn't add format, prefix, or lookup-key nuance beyond the schema, 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 (Gets) and resource (a single agent/managed-device asset) scoped by id, and the parenthetical clarifies that 'agent' equals a managed device, which helps separate it from gorelo_get_custom_asset. It stops short of explicitly naming the sibling it contrasts with.

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 when-to-use guidance, no exclusions, and no reference to alternatives such as gorelo_list_assets (bulk listing) or gorelo_get_custom_asset (a different asset family). The agent must infer the routing from the word 'single' alone.

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 carries a lighter burden — but it adds nothing beyond that: no not-found behavior, no permission requirements, no indication of what a client record contains. For a single-record fetch, the null/error case is the main thing an agent needs and it is unaddressed.

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 short sentence with the resource and lookup key front-loaded and zero filler. It is efficient, though its brevity reflects under-specification rather than a tight description of a complex tool.

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

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

The tool is simple (one required integer, read-only, no output schema needed for a straightforward fetch), and the description covers the operation and the key. Nothing an agent strictly needs to invoke it correctly is missing, though a note on what a client represents would help.

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?

Only one parameter at 100% schema description coverage ('Client identifier.'), so the schema already does the work. The phrase 'by id' merely restates the required field; no added meaning such as where to obtain the id or whether it is the internal id vs an external reference.

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 ('Gets a single client') plus the lookup key ('by id'), which contrasts implicitly with the sibling gorelo_list_clients. It does not explicitly name the list sibling, nor distinguish itself from gorelo_get_contact or other get_* tools, 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?

Usage is only implied: fetch one client when you have its id. No explicit when-to-use, no exclusions, and no pointer to gorelo_list_clients for discovery or gorelo_update_client for modification. Adequate but leaves routing to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lighter burden, but it adds nothing beyond that: no mention of not-found behavior, no note on what fields a contact returns, no scoping or permission 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?

A single front-loaded sentence with zero filler, well matched to a one-parameter lookup. It is efficient but so brief that it borders on under-specification.

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-resource fetch with annotations covering the safety profile and a fully documented parameter, the minimum is met. However, an agent gets no signal about the shape of the returned contact record or error semantics, which a slightly longer description could supply.

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 one parameter and 100% schema description coverage, the schema fully documents the id field. The description's "by id" merely restates it and adds no format, type, or sourcing detail, 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 ("Gets a single contact by id"), and the word "single" implicitly distinguishes it from gorelo_list_contacts. It does not name the sibling explicitly, 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?

Only implies usage through "by id" — the agent can infer it should be used when a contact identifier is already known. There is no explicit guidance on when to prefer gorelo_list_contacts or what to do if the id is unknown or invalid.

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, non-mutating read. The description adds genuine value by disclosing that the response expands into products and labor per service line, which matters given there is no output schema. It says nothing about not-found behavior or permission requirements, so it is useful but 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?

One sentence that front-loads the action and resource, then adds the payload detail. Zero redundancy or 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 one-parameter read tool with a fully documented schema and a readOnly annotation, the description covers both what it does and what comes back (products, labor, service lines), which compensates for the absent output schema. Only minor gaps remain around error/empty-result handling.

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?

Single parameter with 100% schema description coverage ('Identifier of the contract'), so the schema carries parameter semantics. The description adds no format, sourcing, or validation hints for contractId, making the baseline 3 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?

Specific verb + resource ('Gets one contract') with added scope detail about what the payload expands into. The singular 'one contract' implicitly distinguishes it from gorelo_list_contracts, but the sibling is never named, so an agent must infer the pairing.

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: the singular phrasing suggests fetching a known contract ID while gorelo_list_contracts handles discovery. There is no explicit statement of when to prefer this tool, no prerequisite that contractId comes from the list endpoint, and no exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is light. It adds nothing beyond that, though – no mention of behavior when the id doesn't exist (error vs. empty) or of permissions. Minimum viable given the annotation coverage.

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 short sentence with zero filler, and the key constraint ('by id') is front-loaded. Nothing could be removed without losing meaning.

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 annotations covering safety and full schema coverage, the description plus structured data is sufficient to call it correctly. A note on not-found behavior or the returned asset shape would round it out, but there is no output schema to compensate for it.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents customAssetId. The description merely echoes that a lookup key is used, adding no format or example detail beyond the schema, which is the baseline 3 case.

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 ('Gets') and resource ('custom asset') plus the lookup key ('by id'), which distinguishes it from list_custom_assets. It does not explicitly name the sibling it replaces, but the singular 'a single custom asset' makes the split from the list/create/update siblings clear enough.

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 mentions that gorelo_list_custom_assets is the alternative when the id is unknown. Usage must be inferred entirely from the tool name and the 'by id' phrasing.

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, and the description adds nothing beyond that — no mention of whether missing IDs error or return null, permissions needed, or what a document object contains. For a read tool the annotation covers the basics, but no extra behavioral context is offered.

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 front-loaded sentence with no waste, but it is under-specified rather than deliberately concise. Nothing in it fails to earn its place; there simply is very little of it.

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

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

There is no output schema, so the description should convey what a returned document looks like or at least that the full document record is returned. It provides none of that, leaving the agent unable to predict the response shape for a lookup 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?

Only one parameter and schema coverage is 100%, so the schema fully documents documentId ("Document identifier."). The description adds no format hints (e.g., ID prefix or slug) beyond the schema, which is the expected baseline.

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

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

States a specific verb (Gets) and resource (a single document), and the singular form distinguishes it from gorelo_list_documents and the create/update/duplicate siblings. It does not explicitly name those siblings, but the purpose is unambiguous.

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

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

No indication of when to use this instead of gorelo_list_documents, gorelo_get_document_version, or the related-item listing tools. An agent must infer that this is the point-lookup path for a document by ID.

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 safe-read profile, so the description's added value is the disclosure that the response carries the body and attachments — useful since no output schema exists. It stops short of describing error behavior when a versionId belongs to a different document, which the schema hint explicitly raises as a constraint.

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 front-loaded sentence with no filler; the scope and response contents are conveyed in one clause. Nothing could be trimmed 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 two-parameter read tool with full schema coverage and annotations carrying the safety profile, the description covers purpose and return contents adequately. The one gap is behavior on mismatched document/version pairs, which is left to the schema hint.

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

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

Schema description coverage is 100%, so both documentId and versionId are already documented, including the constraint that the version must belong to the document. The description adds no syntax, format, or relationship 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 ('Gets one version of a document') and clarifies the scope as a single version rather than the document or its version list. It does not name gorelo_get_document or gorelo_list_document_versions, so sibling differentiation is implied rather than explicit.

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 statement of prerequisites, and no mention of alternatives among the closely related document tools. The agent must infer the selection rule from the name alone.

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 the safety profile, so the description only needs to add context — and it does, disclosing that the response is expanded to include attachments and line items, which tells an agent it need not make follow-up calls. It omits any note on not-found behavior or whether expansions are optional.

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 short sentence, front-loaded with the verb and resource, with the payload contents attached as a qualifier. Nothing is wasted and nothing important is 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 simple one-parameter read tool with no output schema, the description covers what is returned (the invoice plus attachments and line items) and the annotation covers safety. Minor gaps remain around missing-ID behavior and whether the expansions are always present.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already documents invoiceId. The description adds no format, sourcing, or lookup guidance (e.g., where to obtain the ID), 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 ('Gets one invoice') and the singular 'one' implicitly separates it from the sibling gorelo_list_invoices. It stops short of naming the list alternative explicitly, so it's clear but not maximally differentiated.

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 infers this is the tool for fetching a single invoice by ID rather than enumerating them. There is no explicit when-to-use statement, no mention of gorelo_list_invoices as the alternative, and no prerequisites or error conditions described.

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 useful fact that the returned entity may be a product or a bundle, but says nothing about behavior when the ID is not found or whether related data is included.

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 short sentence, front-loaded with the verb and resource, with the parenthetical clarification earning its place. No waste.

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

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

For a one-parameter read tool this is nearly adequate, but no output schema exists, so the description would ideally say what the item record contains or what happens on a miss. That gap leaves it at minimum viable.

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 itemId parameter, so the schema already carries the semantics. The description's 'by ID' merely restates it without adding format or sourcing guidance, making baseline 3 correct.

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

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

States a specific verb ('Gets') and resource ('catalog item') and clarifies that an item may be a product or a bundle, which is genuine value over the name. It does not name the sibling list_items or otherwise differentiate beyond the 'by ID' qualifier.

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?

'by ID' implies this is the single-record lookup and that list_items would be used for enumeration, but that inference is left to the agent. There is no explicit when-to-use or when-not sentence.

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 this is a safe read, so the description adds nothing on safety. It also says nothing about what happens with an unknown or malformed projectId (error vs empty result), which is the only behavioral question that matters here.

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 short, front-loaded sentence with no filler. It is not padded, though it is also near the lower bound of useful 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 simple 1-param read tool with annotations and full schema coverage, the description is minimally sufficient. Missing only the not-found/error behavior, which an agent would benefit from knowing.

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% for the single required parameter (projectId), so the schema already carries parameter meaning. The description adds no format, ID-type, or lookup hints beyond it; 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 ("Gets a single project"), and "single" implicitly contrasts with the sibling gorelo_list_projects. It does not explicitly name that alternative or distinguish itself from gorelo_get_project_task, but the core 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?

No guidance on when to use this versus gorelo_list_projects or gorelo_get_project_task, and no prerequisites or error conditions stated. The agent must infer usage entirely from the name and schema.

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 nothing beyond that: it does not say what happens if the commentId does not exist, whether comments from other projects are rejected, or what the returned payload contains. For a pure getter the bar is lower, but no added context is present.

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 front-loaded sentence with zero waste. It is efficient, though the brevity reflects under-specification as much as tight writing.

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 low complexity, a fully documented two-parameter schema, and readOnlyHint covering safety, the description is minimally sufficient for calling the tool. However, with no output schema and no mention of return contents or not-found behavior, an agent cannot predict what it will receive.

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 both projectId and commentId carry inline descriptions, so the schema already does the parameter work. The description adds no format, scoping, or constraint information beyond that, which makes the baseline 3 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 gives a specific verb ('Returns') and a specific resource ('one comment on a project'), and the word 'one' distinguishes it from the sibling gorelo_list_project_comments. It stops short of naming that sibling or otherwise explicitly differentiating, so it is clear but not fully disambiguated.

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 gorelo_list_project_comments or gorelo_create_project_comment, and no preconditions or alternatives are mentioned. An agent must infer that this is the single-item lookup path from the tool name alone.

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 safe-read profile, so the description only needs to add context. 'In full' gestures at return completeness but says nothing about not-found behavior, permission scoping on projectId/taskId, or what fields the full payload contains.

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 front-loaded sentence with zero filler. It is efficient, though the brevity shades into under-specification rather than true concision.

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?

There is no output schema, so the description carries the burden of explaining what comes back, and 'in full' is too vague to define the returned shape. For a two-required-parameter getter with no annotations beyond read-only, the definition does not do enough.

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

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

Schema description coverage is 100%, so both required parameters (projectId, taskId) are already documented as strings pointing at the task and its project. The description adds no semantics beyond the schema, which is acceptable at this coverage level but is the baseline, not a contribution.

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 (returns) and resource (one task), and 'in full' hints at full-detail retrieval versus the list sibling. But it never names gorelo_list_project_tasks or gorelo_get_project_task_approval, so an agent must still infer which task-retrieval tool applies.

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 when-to-use guidance, no mention of alternatives such as list_project_tasks for multiple tasks or the approval sub-resource tool. The agent is left to infer selection purely 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The phrase 'with its approvers' adds useful context about what the response includes, which goes beyond the annotations. However, with no output schema, no further behavioral details (error cases, whether approvers is always present) are given.

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 front-loaded sentence with no filler. Every word (verb, singular resource, included relation) 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 read getter with full annotation and schema coverage, the description is minimally adequate. Without an output schema, the sole cue about return data is 'with its approvers', leaving the shape of the approval object unexplained.

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 each parameter documented including the origin of approvalId ('from the conversations endpoint'). The description adds no parameter detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('Gets') and resource ('one approval on a task'), which distinguishes it from the sibling gorelo_create_project_task_approval. It doesn't clarify what an 'approval' is or how it differs from gorelo_get_ticket_approval beyond the task context, so it stops short of full sibling 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?

There is no guidance on when to use this tool versus alternatives and no exclusion conditions. The agent must infer usage entirely from the name and the fact that an approvalId is required.

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 only job is to add context — and it adds none. It says nothing about behavior when the comment, task, or project ID is invalid, whether it returns deleted comments, or if any permission scoping applies.

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 nine-word sentence with no filler and the resource front-loaded. It is lean to the point of under-specification, which is a completeness problem rather than a conciseness one.

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

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

For a simple read-only get-by-id tool with a fully documented three-parameter schema and a readOnlyHint annotation, this is close to adequate. The remaining gap is the absent output schema combined with no description of the returned comment's shape or not-found behavior.

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% — each of projectId, taskId, and commentId is documented with its parent-child relationship — so the baseline of 3 applies. The description confirms the three IDs form a hierarchy (project → task → comment) but adds no meaning beyond the schema.

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

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

States a specific verb and resource ("Returns one comment on a task") with the singular scope implied by "one". It is clear, but it never names the sibling that lists many comments (gorelo_list_project_task_comments) or the one that creates them, so the agent must infer the distinction from the name alone.

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 reach for this tool versus gorelo_list_project_task_comments or gorelo_get_project_task. The get-by-id shape is implied by the required IDs in the schema, but the description contributes no usage guidance or preconditions.

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 owes additional context and delivers none. It says nothing about error behavior for a missing/invalid ticketId, permission requirements, or the shape of the returned ticket, all of which matter for a get-by-id call with 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?

The single sentence is free of redundancy and front-loaded, but its brevity reflects under-specification rather than disciplined concision. There is no wasted text, yet almost nothing is conveyed.

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 no output schema and no nested objects, the description should at minimum hint at what is returned or what happens on a not-found ID. Neither is present, so an agent knows only that a ticket comes back.

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% for the single ticketId parameter, so the schema already defines it and the baseline is 3. The description adds no semantics beyond the schema, such as whether the ID is a numeric string, internal ID, or external reference.

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?

"Gets a single ticket" states a concrete verb and resource, and the word "single" distinguishes it from the sibling list_tickets. However, it does not distinguish it from the other get_* siblings (get_ticket_approval, get_ticket_comment) or indicate what a ticket record contains, leaving the purpose only minimally specified.

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 explicit guidance on when to use this tool versus list_tickets, update_ticket, or the related get_ticket_* tools. The requirement of a ticketId implies retrieval-by-identifier, but that inference is left entirely to the caller.

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's job is lighter. It does add useful context that this endpoint is the sole home of approval status and that conversations are intentionally lean, but says nothing about response shape, permissions, or whether approver data can be paginated or partial.

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 core action front-loaded; the second sentence earns its place by explaining why approval status is not available elsewhere. Slightly indirect phrasing ('This is where approval status lives') rather than a crisp statement of scope keeps it off a 5.

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

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

For a two-required-parameter read tool with full schema coverage and no output schema, the description covers what is retrieved (the approval plus its approvers) and why it exists as a separate endpoint. The only gap is the shape of the returned approval object, which matters somewhat given there is no output schema.

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

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

Schema description coverage is 100%, so both ticketId and approvalId are already documented, including the note that approvalId comes from the conversations endpoint. The description adds no additional syntax, format, or sourcing guidance 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 ('Gets') and a precisely scoped resource ('a single approval on a ticket, with its approvers'), which separates it from the plural/list siblings like gorelo_list_ticket_conversations. It doesn't name the parallel task-level tool (gorelo_get_project_task_approval) that an agent might confuse it with, so differentiation is strong but not complete.

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 second sentence implies usage — look here for approval status because the conversations list deliberately omits it — which is a genuine routing hint. However, it never states an explicit 'use this when...' condition or names a specific alternative sibling tool to prefer.

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 genuine value beyond that: it discloses the return shape (same as a list item) and the key behavioral difference that full BodyHtml is always present and BodyTruncated is omitted, which is exactly the context needed with no output schema present.

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 that front-load the operation and then explain the one meaningful difference from a list item. No filler; 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 simple two-param read tool with fully documented params and readOnly annotations, the description covers the essential missing piece (return shape and the BodyHtml/BodyTruncated distinction). It does not mention error behavior for missing IDs, but nothing critical is absent.

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

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

Schema description coverage is 100%, so both ticketId and commentId are already documented in the schema. The description adds no additional meaning about identifier format or scoping, 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?

Specific verb+resource ('Gets a single comment on a ticket') clearly states what it returns. It implicitly contrasts with the list variant ('a single comment'), but never names gorelo_list_ticket_comments or the parallel get_project_comment/get_project_task_comment siblings 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?

The singular framing implies fetching one comment by ID rather than enumerating, which is enough to distinguish from the list tool. But there is no explicit when-to-use guidance, no mention of when to prefer the list endpoint, and no prerequisites 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 nothing beyond that — no mention of what happens with an invalid or missing id, whether archived/deleted entries are returned, or any permission scoping. For a trivial getter this is tolerable but still a gap.

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 front-loaded sentence with no filler; every word contributes to identifying the operation and its scope.

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

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

Given a one-parameter getter with readOnlyHint and a fully documented schema, the description is close to sufficient, but with no output schema it never indicates what the returned entry contains or how a not-found case behaves.

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?

Only one parameter and schema coverage is 100%, with the schema itself describing it as 'Time entry to read.' The description's 'by id' adds no syntax, 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 ('Gets') and resource ('a single time entry by id'), so an agent can tell it fetches one record rather than a collection. It doesn't explicitly name gorelo_list_time_entries or gorelo_update_time_entry as the alternatives, but 'single ... by id' implicitly separates it from the list sibling.

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

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

No when-to-use statement, no prerequisites, and no alternatives named. An agent must infer that this is the tool to call when it already holds a time entry id and wants the full record rather than a 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?

The readOnlyHint annotation already establishes the safety profile, so the description needed to add context such as behavior on a nonexistent id, what fields come back, or whether errors are thrown. It adds no behavioral information beyond what annotations and the name already 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?

A single front-loaded sentence with zero filler; every word contributes to identifying the operation.

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 annotation, the description is sufficient to call it correctly. Only minor behavioral detail (not-found handling) is absent.

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

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

Schema description coverage is 100% for the single checkId parameter, so the schema carries the parameter documentation. 'By id' only restates that the identifier selects the record and adds no format or validity 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 ('Gets') and resource ('uptime check') plus the retrieval key ('by id'), which distinguishes it from gorelo_list_uptime_checks. It does not name the sibling 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?

'A single uptime check by id' implies this is the fetch-one counterpart to the list tool, but there is no explicit when-to-use guidance and no named alternative. Adequate inference is required.

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 only added value is the cross-client scope phrase. It says nothing about pagination via cursor, the default page size of 50, default sort order, or the shape of the returned alert records.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity reflects under-specification rather than tightly packed 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 nine-parameter, paginated list tool with no output schema, the description omits pagination behavior, result ordering, and any indication of what an alert record contains. An agent can infer it is a read, but not how to page through or interpret results.

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 one of the nine parameters, including enum-like id mappings and cursor semantics, is already documented in the schema. The description adds no parameter 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?

The description names a specific verb (Lists) and resource (alerts) and adds a scope qualifier ('across all your clients'). The only sibling in the alert family is gorelo_create_alert, so no explicit disambiguation is strictly needed, but the scope phrase sits slightly at odds with the clientIds filter in the schema.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no statement about what to do when results are truncated. 'Across all your clients' is the only contextual hint, and it is never framed as a when-to-use rule.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description goes further by disclosing sort order (newest first) and that key values are deliberately withheld from the payload. That field-exclusion detail is the kind of context an agent cannot infer from the schema or annotations.

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

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

Two tight sentences, action and ordering first, the security caveat second. No filler and nothing an agent must read past to get the point.

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 no output schema, the description correctly sketches what comes back (names and details, not secret values), and pagination lives in the schema. Adequate for a simple zero-required-parameter read tool, though an explicit note that the listing is unfiltered would close the last gap.

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

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

Schema coverage is 100%, with cursor and pageSize fully documented including range and default, so the description carries no burden here. It adds nothing about pagination behavior, which is fine given the schema covers it — 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 and resource ('Lists your Gorelo API keys') plus ordering ('newest first') and field scope ('names and details only, never the key values'). No sibling tool covers API keys, so an agent can immediately tell this is the only key-listing route.

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 — browse/inspect API keys — and the sentence 'never the key values' usefully heads off a misuse attempt (expecting secrets back). But it never states when to use this versus anything else, nor where to go if the actual key value is needed.

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 genuinely new behavioral facts: results are cursor-paginated and ordered by createdOn descending, which tells the agent how to iterate and what the first page means.

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

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

Two sentences, both load-bearing: the first states the resource and pagination model, the second states sort order. Front-loaded and free of repetition of the schema.

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

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

For a nine-parameter, fully documented list tool with a read-only hint and no output schema, the description covers the essentials of how to page and what ordering to expect. The only gap is that, absent an output schema, it never indicates what a returned asset 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% across all nine optional parameters, including the cursor/pageSize mechanics that the description only alludes to. The description adds no filter semantics (e.g., how query matches, whether date bounds compose) beyond what the schema already documents, 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?

Names a specific verb and resource and narrows the scope to 'agent (managed device) assets for the service provider', which implicitly separates it from the custom-asset siblings in the toolset. It does not name the closest alternative (gorelo_list_custom_assets) explicitly, so an agent must infer 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?

Usage is only implied: the description tells you the tool enumerates devices page by page, newest first, with no statement of when to prefer it over gorelo_list_custom_assets or gorelo_get_asset. No prerequisites, exclusions, or alternative routing are given.

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 value by explaining how the returned Id is consumed (BillingRoleId on time entries), but says nothing about pagination, result shape, or whether roles are provider-scope vs client-scope. Reasonable but 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 sentences, zero waste, with the core purpose front-loaded and the downstream hint second. Every sentence earns its place.

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

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

For a parameterless, read-only list tool with no output schema, the definition covers what the agent needs to select and use it, including the downstream Id usage. A brief note on what the list returns (Id, name, scope) 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?

The tool takes zero parameters, so per the baseline this scores 4. The description does not need to explain inputs, and it does not misleadingly imply any.

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 ('Lists the billing roles configured for the service provider'), which is unambiguous and distinct from generic list_* siblings like list_users or list_groups. It stops short of explicitly differentiating itself from adjacent admin-listing tools, but the resource noun is specific enough for an agent to identify 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?

The second sentence gives concrete downstream guidance: use a role's Id as BillingRoleId when logging time against a ticket, effectively pointing to the time-entry workflow. It lacks an explicit 'when not to use' or a named sibling alternative, which keeps it below 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, and the description adds nothing beyond that—no pagination behavior, no statement about what happens when the client has no locations or does not exist, and no indication of return shape. For a list tool the description's contribution is essentially nil beyond the annotations.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though its brevity borders on under-specification rather than disciplined concision.

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 list tool with full schema coverage and an existing readOnlyHint, the minimum needed to call it correctly is present. Still, useful context such as result ordering, pagination, or empty-result behavior is absent, leaving it merely adequate.

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

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

Schema coverage is 100%, so the single clientId parameter is fully documented in the schema as the 'Client identifier.' The description adds no format or semantic detail beyond that, which is the expected baseline when the schema does the work.

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 ('Lists') with a specific resource ('locations') and its scope ('for a given client'), so the operation is unambiguous. It does not, however, distinguish itself from related siblings such as gorelo_get_client, which could plausibly return location data too.

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 instead of gorelo_get_client or gorelo_list_clients, and no prerequisites or exclusions are stated. The only implied usage comes from the required clientId parameter.

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 useful behavioral context beyond annotations by disclosing cursor pagination and the ascending client-id sort order, but it says nothing about permissions, rate limits, or what fields 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 tight sentences with zero waste. The core purpose is front-loaded, and the pagination and ordering details earn their place as non-obvious behavioral context.

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

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

For a list tool with a fully documented eight-parameter schema and a readOnly annotation, the description covers the important non-schema behavior: pagination method and sort order. It stops short of describing return fields, but no output schema exists and the schema handles filtering details, 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?

Schema description coverage is 100%, so all eight parameters (query, cursor, pageSize, statusIds, date filters) are already documented in the schema. The description's mention of cursor pagination and sorting adds little parameter-level meaning beyond that, making 3 the appropriate baseline.

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

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

States a specific verb and resource ('Lists clients') and narrows the scope to 'the service provider.' It does not explicitly differentiate from siblings like gorelo_get_client or gorelo_list_client_locations, but the resource noun is clear enough that an agent can distinguish this as the collection endpoint.

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 the paginated list endpoint and mentions cursor pagination, but it does not say when to prefer this over gorelo_get_client for retrieving a single client or when to use gorelo_list_client_locations. No explicit exclusions or alternatives are provided.

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 comes from structured data. The description adds genuinely useful behavior beyond that: results are sorted by contact id ascending (oldest first) and paging is cursor-based. It does not cover result size limits, error conditions, or what a page contains.

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

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

Two sentences, zero filler, and the key operational facts (pagination style, sort order) are front-loaded. Nothing is repeated from the schema descriptions.

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

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

With 10 optional parameters and no output schema, the description is adequate on ordering and pagination but says nothing about the shape or fields of returned contacts, which the agent must infer. It is sufficient to make the call but not to interpret the response.

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

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

Schema description coverage is 100%, covering query, cursor, pageSize clamping, clientIds/clientId deprecation, statusIds enum values, and date filters. The description only mentions the optional client filter, which the schema already explains, so it adds no meaning beyond it. 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 ('Lists contacts'), plus scope ('for the service provider') and ordering. It distinguishes itself from gorelo_get_contact and gorelo_create_contact only implicitly through the verb 'list', 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?

Usage is implied by 'optionally filtered by client' and the pagination mention, but there is no explicit guidance on when to prefer this over gorelo_get_contact or on how to page through results versus fetching a single record. No exclusions 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 already declares the safety profile, so the bar is lower. The description does add real context beyond the annotation by disclosing that service lines are embedded in each returned contract (valuable since there is no output schema), but it says nothing about pagination flow or the default exclusion of Archived contracts, which lives only in the 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?

A single front-loaded sentence with zero filler; the resource and its notable return characteristic are stated immediately. Nothing is restated 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 fully-optional-parameter read tool with 100% schema coverage and no output schema, the description covers what the tool returns (contracts plus their service lines), which is the main thing the schema cannot convey. It falls short only on pagination behavior and the filter-based usage context, which are minor gaps given the rich schema.

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

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

Schema description coverage is 100%, so cursor semantics, page-size clamping, and the statusId enum mapping are already fully documented in the schema. The description adds no parameter meaning 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 (Lists) and resource (billing contracts) plus the nested service-line content of each record. It does not explicitly distinguish itself from the sibling gorelo_get_contract or mention that filters are available, so sibling differentiation is only implicit in the plural name.

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 mention of the clientId/statusId filters that would make this the right choice over gorelo_get_contract, and no note about when another tool is preferable. The agent must infer usage entirely from the name and schema.

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 description need not repeat that. It adds the useful gloss that this is a fixed catalog of values that can be assigned to a custom asset, distinguishing it from a data listing, but says nothing about ordering, pagination, or whether the list is static.

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 short sentence, front-loaded with the verb and resource, with no filler. It is arguably too terse rather than too long, but nothing is wasted.

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 with annotations covering safety and no output schema, the definition is minimally adequate. It leaves open what a returned 'hardware type' looks like (id vs name) and whether the caller should pass it directly to create/update_custom_asset, which an agent would need to know.

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 to document; baseline 4 applies. No misleading parameter hints are present.

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 gives a specific verb+resource ('Lists the hardware types') and adds scope with 'a custom asset can be given,' making clear this is the enum of assignable hardware types. It does not name or differentiate itself from any sibling, but no sibling covers this resource, so confusion risk is low.

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 explicit when-to-use or when-not-to-use guidance, and no mention of the obvious related tools (gorelo_create_custom_asset, gorelo_update_custom_asset) whose fields this list would populate. Usage is only inferable from the purpose statement.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description still adds real behavioral context by disclosing cursor pagination and the default sort order (createdOn descending, newest first), which an agent needs to reason about paging through results. It stops short of describing what a returned item contains or whether the cursor is stable across filters.

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

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

Two tight sentences with zero waste; scope and pagination come first, and the sort order follows. 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?

With eight optional filters, no output schema, and readOnlyHint carrying safety, the description covers the essentials: scope, paging model, and default ordering. The notable remaining gap is that, absent an output schema, it says nothing about the shape of a returned asset, so an agent cannot anticipate fields without a follow-up call.

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 is already documented, and the description adds no filter semantics beyond the schema (it mentions cursor pagination, which the cursor param already explains). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Lists custom (non-agent) assets") plus the scope "for the service provider," and the parenthetical "non-agent" implicitly separates it from gorelo_list_assets. No sibling is named explicitly, so an agent must infer the boundary, keeping it below 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: the "non-agent" qualifier suggests when to pick this over the general asset list, but there is no explicit when-to-use, when-not-to-use, or named alternative (gorelo_list_assets, gorelo_get_custom_asset). Adequate but with a clear routing 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?

Annotations already declare readOnlyHint=true, and the description adds useful behavioral detail beyond that: results are sorted by DeletedOn ascending, then type id, then id, and pagination is cursor-based. It does not describe retention limits or the deleted-record payload shape, which keeps it from 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, front-loaded with the core purpose and followed by the sorting and pagination behavior. There is no redundant or filler text.

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?