Getfly CRM MCP by usefulapi

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the write/non-idempotent profile is covered. The description adds real value beyond that: it discloses the notification side effect on opportunity followers and that the comment is attributed to the supplied user, which an agent cannot infer from the structured fields.

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

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

Three short clauses: action, side effect, endpoint. The operation type is front-loaded and nothing is redundant.

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

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

For a three-parameter write tool with no output schema, the description covers action, attribution, side effects and endpoint. It could mention success behavior or that the new comment id is returned, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%: content, user_id and opportunity_id are all documented in the schema, including the note that opportunity_id is the numeric id and not the code. The description adds only the notion of posting "as the given user", which slightly reinforces user_id but does not extend 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?

Specific verb plus resource: "Post a comment in the discussion of an opportunity", fronted with a WRITE marker that separates it from the read-side sibling getfly_list_opportunity_comments. It stops short of naming that sibling, so the differentiation is implied by the verb 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?

The "WRITE:" prefix and the endpoint signal that this creates rather than lists comments, which implies the usage context. However, there is no explicit when-to-use statement, no mention of prerequisites such as needing the opportunity to exist, and no named alternative.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds little beyond a redundant 'WRITE:' prefix and the HTTP endpoint; it does not say whether completion is reversible, what permissions are needed, or what happens on an already-completed task (idempotent behavior is only in 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?

Single front-loaded sentence with the write nature flagged first, plus a terse endpoint. No filler, though the endpoint string is arguably duplicated by the description's own 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 one-parameter mutation with rich annotations and no output schema, the definition covers what an agent needs to invoke it correctly. The remaining gap is behavioral detail (permissions, reversibility), which annotations partially cover.

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 only one parameter and 100% schema description coverage, the schema carries the semantics (type, length bounds). The description merely restates that the task code is the key, adding no format detail such as whether it accepts a numeric ID or prefixed code format.

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

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

States a specific verb and resource ('Mark a task as completed') plus the identifier required ('by its task code'), which cleanly separates it from siblings like getfly_create_task, getfly_get_task and getfly_list_tasks. The endpoint is a bonus confirmation of the 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?

Usage is implied rather than stated: 'mark as completed by task code' makes the input precondition obvious, but there is no explicit when/when-not guidance and no named alternative (e.g., a general update_task tool is not referenced). Adequate for a single-purpose verb, but leaves routing mostly 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description meaningfully adds that creation 'may trigger the workflows and notifications set up in the CRM' and that the customer code must be unique (omitted → auto-generated). It does not mention auth requirements or error behavior on duplicate codes.

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 mutation intent is front-loaded in the first word, and the four sentences each convey distinct constraints (uniqueness, name-matching, optional contact, side effects). The enumeration of name-matched fields is slightly dense but 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 20-parameter nested-object mutation with no output schema, the description covers the tricky constraints well but says nothing about what is returned (e.g., created account id) and omits custom_fields entirely. Adequate but with a clear gap for an agent needing to chain on the result.

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 only 65% schema coverage across 20 parameters, the description carries real weight: it explains that account_code is unique and optional, that type/source/industry/relationship/country/province/district/ward must be matched by configured NAME (a non-obvious constraint), and that contact is a single optional primary contact. It leaves custom_fields and the return/ID behavior unaddressed.

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

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

The description opens with a specific verb and resource ('Create a new customer (account)') and the 'WRITE:' prefix immediately signals mutation, distinguishing it from read siblings like getfly_get_account and getfly_list_accounts as well as from getfly_update_account.

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 clearly establishes the create context and adds operational rules (unique account_code, names must match Getfly-configured values, one optional primary contact). It also cross-references getfly_list_users for account_manager_username. However, it never explicitly contrasts with getfly_update_account for the case where the customer already exists.

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

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

The description adds real value beyond annotations by disclosing that the call also creates or links a customer and contact, and that the assigned user and campaign rules may be notified — an external side effect that fits openWorldHint=true. It does not, however, say what happens on duplicate customers, whether the write is reversible, or what the response contains, and there is no output schema to compensate.

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

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

Three short sentences, front-loaded with the "WRITE:" marker and the core action; every sentence carries information. The trailing endpoint path is marginal value but harmless.

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

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

For a 9-parameter mutation tool with 6 required fields and no output schema, the description covers the action, the entity linkage, and the notification side effect well. It stops short of describing return payload or failure modes, which an agent would want for a write 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 coverage is 78%, so the schema already documents nearly every parameter, including the optional account_code for existing customers and the lookup hints for campaign_code and recipient_username. The description only restates the create-or-link behavior for the account/contact fields, adding little syntax or format detail on top of 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?

Opens with a specific verb and resource ("Create a sales opportunity in a campaign") and names the two related entities involved (customer, assigned user). It partially separates itself from getfly_create_account by noting the customer/contact are created or linked as a side effect, but it never explicitly says when to call create_account instead.

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 the create semantics; there are no explicit when-to-use/when-not conditions or named alternatives. The prerequisite lookups (campaign_code, recipient_username) appear only inside the schema descriptions, not the tool description.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=true, so the safety profile is covered. The description still adds real value beyond that: it discloses that referenced entities must already exist (name-resolution failure risk) and that "the assignee may be notified by Getfly" — an unintended-side-effect warning an agent cannot infer from 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?

Three short sentences, zero filler, front-loaded with the operation class and resource. The endpoint reference is tucked at the end where it belongs.

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

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

For an 11-parameter creation tool this covers the critical preconditions (entities must exist, values given by name). The main remaining gap is outcome: nothing says what is returned on success (e.g., created task code/ID) so an agent can't tell if chaining is possible, and no output schema compensates.

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 parameter is already documented in structured form. The description reinforces the naming convention (project/type by NAME, users by login name) which is genuinely useful for correct value selection, but it does not add format, default, or interaction semantics beyond that.

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

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

"WRITE: Create a task" names a specific verb and resource, and the qualifiers (optionally in a project, assigned to a user, linked to a customer) delineate the scope precisely. The WRITE prefix plus the resource name makes it trivially distinguishable from sibling creators like getfly_create_ticket or getfly_create_opportunity.

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 through 'optionally in a project' and the requirement that project/task type exist in Getfly, which quietly conveys prerequisites. But it never states when to prefer this over alternatives such as getfly_create_account/getfly_create_ticket, nor any when-not conditions or failure modes.

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, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior: Getfly may notify the support team (an external side effect), ticket content may contain HTML, and the call maps to POST /api/v6.1/ticket.

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

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

Three short sentences with the write semantics front-loaded, followed by the constraint, then the side effect and endpoint. No sentence is redundant and nothing buries the important constraint.

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

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

For a 9-parameter mutation with no output schema, the description covers the two non-obvious constraints (name-based lookups, HTML content) and the external side effect. It omits what the call returns (e.g., created ticket id) and whether omitting cate_name/status_name is legal, which would help given only 2 of 9 params are required.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description earns more by clarifying that cate_name and status_name are resolved by NAME against configured Getfly values rather than arbitrary strings. It also reinforces that ticket_content accepts HTML, which the schema mentions but understates.

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

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

The description opens with an explicit verb+resource ('WRITE: Create a support ticket') and adds scope ('optionally for a customer'), which clearly separates it from read siblings like getfly_get_ticket and getfly_list_tickets. It stops short of naming a sibling alternative, but the create-vs-read distinction 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?

It states a concrete prerequisite for correct invocation: category and status must match names configured in Getfly, and it routes the agent to getfly_list_ticket_categories and getfly_list_ticket_statuses to obtain them. It gives no explicit 'when not to use this' exclusion, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them by naming the upstream endpoint (GET /api/v6.1/account?account_code=) and enumerating the fields in the returned profile, which matters because there is no output schema.

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

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

Two compact fragments, front-loaded with the return scope followed by the endpoint hint. No filler sentences and nothing repeated from the title.

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

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

With no output schema, the description compensates by listing what the profile contains, and annotations cover the read-only profile. For a single-record fetch, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description only adds an example code format (KH/2025/000001), which is a small but genuine extra; the fields parameter is not elaborated on 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 clearly it returns a single customer looked up by customer code, and enumerates what the payload contains (contacts, custom fields, type, source, industry, manager, revenue). The singular "one customer" implicitly contrasts with list tools, but no sibling is named, so it stops just short of a 5.

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

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

Usage is only implied: the reader infers this is the fetch-by-id counterpart to getfly_list_accounts and that account_code must already be known. There is no explicit when-to-use / when-not-to-use statement or named alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavior of its own by disclosing the return shape (status id, name, per-stage opportunity counts) and the underlying endpoint. It omits error behavior when zero or two identifiers are supplied.

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, front-loaded with what is returned, followed by the calling constraint and endpoint. No filler; the endpoint reference is the only marginal-content 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?

With no output schema, the description appropriately summarizes the returned fields, and it states the identifier constraint the schema leaves implicit. Missing only edge-case behavior (both/neither identifier, unknown campaign) for full completeness.

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

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

Schema coverage is 0%, so the description carries the burden — and it does communicate the crucial mutual-exclusivity rule ('exactly one of campaign_id and campaign_code') that the schema itself does not encode (neither is required, no oneOf). It does not describe formats, e.g. that campaign_code is a bounded string.

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 resource and scope ('the pipeline stages of one campaign') and even enumerates the returned fields (status id, name, opportunity count). It is clearly distinct from getfly_list_campaigns and getfly_move_opportunity_stage in spirit, though no sibling is named 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?

It gives an explicit calling constraint: 'Pass exactly one of campaign_id and campaign_code.' That is actionable context, but it does not say when to prefer this tool over alternatives (e.g. list_campaigns to first discover an id/code) or what happens on violation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds value by disclosing the concrete fields returned and the API endpoint/version. It still doesn't mention error behavior for an unknown code or whether the response is full-detail vs. summary.

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 compact sentence with the resource and example code front-loaded, followed by the returned attributes and endpoint. No filler or redundancy.

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

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

With no output schema, the description carries the burden of return-value disclosure and does so by naming the key attributes returned. A two-parameter read-only lookup at 100% schema coverage is otherwise well 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema's bare 'Opportunity code' by giving a concrete format example (CH2284). The 'fields' parameter is left entirely to the schema.

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

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

States a specific verb+resource: fetch one opportunity by its code, and lists the returned attributes (stage, probability, handler, customer, campaign). The singular 'one ... by its code' implicitly separates it from getfly_list_opportunities, though it never names that 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?

The phrasing 'by its code' implies you must already know the opportunity code, which nudges the agent toward the list/search tools first, but this is never stated explicitly. No exclusion, prerequisite, or alternative tool is named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the API endpoint and the field groups returned, but says nothing about error behavior for unknown codes or pagination, which is acceptable given 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?

Two compact clauses: what it returns, then the endpoint. Front-loaded with the identifying resource and code example, zero filler.

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

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

With no output schema, the description usefully enumerates the returned field groups (prices, VAT, variants, custom fields), which is the main thing an agent needs. A note on behavior for a missing/invalid code would round it out, but nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description contributes the concrete code example (SP.00192), giving useful format intuition, but otherwise defers to the schema — 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 ('One product by its code') and enumerates what the response contains (prices, unit, category, VAT, variants, custom fields), which distinguishes it from getfly_list_products without naming it explicitly. The sibling differentiation is implied by 'one product' rather than stated.

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

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

Usage is implied — fetch a single product when you have its code — but there is no explicit when-to-use/when-not guidance and no mention of getfly_list_products as the alternative for searching by name or listing.

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 declare readOnlyHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds the specific API endpoint and the payment_periods behavior, but does not describe error behavior, permissions, rate limits, or pagination.

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

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

The description is two tight sentences plus the endpoint, with the retrieval scope and field list front-loaded and no redundant filler.

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

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

For a read-only two-parameter get tool with no output schema, the description gives enough context: the resource, the lookup key, the returned data categories, and the payment schedule option. The main minor gap is that it does not mention not-found or error 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%, so baseline parameter semantics are already strong. The description adds useful meaning by explaining that adding payment_periods to fields includes the payment schedule, which goes beyond the generic fields description.

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

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

The description clearly states it retrieves a single sales order by order code and enumerates the returned data: status, payment status, amounts, customer, line items, shipping info, and custom fields. It distinguishes itself from the list sibling by singular scope and required order code.

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 implication is that this tool should be used when an order code is known, but it provides no explicit when-to-use versus alternatives guidance. It does not mention using getfly_list_sale_orders to find an order code first or state exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /api/v6.1/task) and the field set returned, but says nothing about error behavior for an invalid task_code or whether custom fields require special handling.

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 fragments with the resource and its identifying key front-loaded, then the returned fields, then the endpoint. Every element carries signal and 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?

With no output schema, the description usefully enumerates the return fields, which is the main thing an agent needs. Minor gaps remain around error cases and pagination/field-selection interaction, but the core read contract is 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 both task_code and fields are documented in the schema, including that task_code comes from getfly_list_tasks. The description adds no parameter detail beyond what the schema already provides, 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+resource (retrieve one task by task_code) and enumerates the returned attributes (status, progress, assignee, project, dates, custom fields), which separates it from the plural list sibling. It stops short of naming getfly_list_tasks explicitly, so sibling differentiation is implied rather than stated.

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

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

Usage is implied: call it when you already have a task_code. There is no explicit when-to-use guidance, no exclusion of getfly_list_tasks for lookups without a code, 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying HTTP endpoint, which does little to reveal behavior such as error handling or the default field set returned.

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

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

Two short fragments, front-loaded with the resource and scope. The trailing 'GET /api/v6.1/ticket' is implementation detail of marginal value to an agent but costs little.

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

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

For a simple two-parameter read tool with a fully documented schema, the definition is mostly sufficient. However, with no output schema present, the agent gets no indication of what a ticket object contains or what the 'default set' of fields is.

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

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

Schema description coverage is 100%: the ticket_code parameter documents its source (getfly_list_tickets) and the fields parameter documents the comma-separated syntax and default behavior. The description adds nothing beyond this, 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?

Identifies the resource (a single support ticket) and the lookup key (ticket code), which implicitly distinguishes it from getfly_list_tickets. It lacks an explicit verb ('Retrieve'/'Fetch'), but the intent 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: you need a ticket_code, and the schema notes it comes from getfly_list_tickets. There is no explicit statement of when to choose this over the list tool or what happens if the code is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint, but does not mention auth requirements, rate limits, or return behavior; with annotations present, this is adequate 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?

The definition is extremely compact: one sentence carries the key selection constraint and the endpoint is included without additional filler. It is front-loaded and every element has a 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?

For a simple read-only lookup with full schema descriptions and annotation coverage, the description provides enough to call the tool correctly. It could explicitly note that a single user object is returned, but with no output schema that is a minor omission.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by stating that exactly one of user_id and user_username must be supplied, which is not expressed in the schema itself and is important for correct invocation.

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 indicates retrieval of a single user by id or login name, which distinguishes it from getfly_list_users. It is somewhat telegraphic ('One user by...') and does not use an explicit verb such as 'retrieve', but the resource and scope are unambiguous.

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

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

The parenthetical 'exactly one of user_id and user_username' gives a concrete usage constraint. However, it does not explicitly compare against the sibling list tool or describe when to prefer this over other lookups, so guidance 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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the endpoint path and default ordering, but the ordering ('newest id first') is already stated in the sort parameter's schema description, and pagination behavior is left to the offset schema. Net added behavioral context is modest.

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 dense paragraph with the core purpose and return fields front-loaded, followed by filters and ordering. Efficient, though the long comma-delimited field run is slightly less scannable than a structured list.

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 compensates by listing the returned attributes, and it enumerates filter fields for the free-form filters object. Pagination semantics (next_offset) live in the schema, so this is close to complete; only explicit sibling routing is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by enumerating valid filter field names (industry, relation_id, sale_order_status, account_manager, date gte/lte/between) that the generic filters object with only propertyNames: string cannot convey. This meaningfully supplements 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 ('List customers (accounts)') and enumerates the returned attributes (code, name, phone, email, revenue, contacts), so an agent knows exactly what it gets. It doesn't explicitly contrast with getfly_get_account, leaving sibling differentiation to be inferred from the 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 enumerated filter list and 'Newest first' hint at retrieval use cases, but there is no explicit statement of when to use this versus getfly_get_account, getfly_list_opportunities, or any exclusion. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the endpoint URL and the set of returned fields, which is useful context, but it does not disclose pagination behavior, default field behavior, or any rate-limit/auth traits beyond what annotations provide.

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

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

The description is a single front-loaded sentence followed by the endpoint path. Every clause earns its place by naming the resource and the returned fields, with no redundant or filler content.

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

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

For a read-only list tool with one optional parameter, full schema coverage, annotations, and no output schema, the description provides enough detail about what is returned. Minor gaps remain around pagination and default fields, but an agent has what it needs to invoke the tool correctly.

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

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

Schema coverage is 100%, and the single optional 'fields' parameter is fully documented in the schema, including format and example. The description does not add meaning beyond the schema for this parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: list sales campaigns (opportunity pipelines). It also enumerates the main returned attributes, making the purpose unambiguous. It does not explicitly distinguish itself from close siblings like get_campaign_stages or list_opportunities, so it falls short of a 5.

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

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

Usage is implied by the verb 'List' and the resource name, but there is no explicit guidance on when to use this tool versus get_campaign_stages, list_opportunities, or other list endpoints. No exclusions or prerequisites are stated.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description contributes beyond that by naming the returned field set (id, name, parent, level, financial account) — valuable because there is no output schema — and by citing GET /api/v6.1/funds. It omits pagination behavior and any rate-limit or ordering notes, keeping it below a 5.

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

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

One sentence plus an endpoint reference, zero padding, and the disambiguating gloss on 'funds' is front-loaded where it matters most. 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 six-parameter read tool with a complex filters object, the rich schema carries parameter semantics and the annotations carry the safety profile; the description fills the gap left by the absent output schema by listing returned fields. What remains unmentioned — pagination across offset/limit, default ordering behavior, response envelope — is minor and partly recoverable from the schema.

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

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

Schema description coverage is 100%, with sort, limit, fields, offset, direction and the nested filters object each documented in the schema including operator syntax and examples. The description adds nothing about parameters, so the baseline 3 applies — the schema does all the work here.

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

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

States a specific verb and resource ('List the cash/bank funds') and immediately disambiguates what a 'fund' is with the parenthetical 'accounts for receipts and payments', which matters because a sibling named getfly_list_accounts exists. It also enumerates the identifying fields returned and cites the exact endpoint. It stops short of explicitly contrasting itself with that sibling by name, so a 4 rather 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?

Usage is only implied: an agent can infer this is the read path for the funds resource, and the parenthetical hints it is the right choice when receipts/payments accounts are needed. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. vs getfly_list_accounts), which 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds the endpoint and returned fields, but it does not describe pagination behavior, rate limits, authentication needs, or other operational traits.

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

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

The description is front-loaded and compact: it states the resource, returned fields, campaign filtering, and endpoint in only a few sentences. There is no filler or repetition.

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

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

There is no output schema, and while the description names some returned fields, it does not explain the response envelope, pagination behavior, or how next_offset should be used. The input schema fully covers parameters, but the description remains incomplete regarding return values.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including filters, sorting, pagination, and campaign_code provenance. The description reinforces campaign_code and lists returned fields, but it adds little meaning beyond the structured 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 states a specific verb and resource ("List sales opportunities") and lists the returned fields. It clearly identifies this as a list operation, but it does not explicitly distinguish it from sibling tools such as getfly_get_opportunity or getfly_list_campaigns.

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 the list operation and the campaign_code filter, but there is no explicit guidance on when to use this tool versus get_opportunity or other opportunity-related siblings. It mentions campaign_code comes from getfly_list_campaigns, which is useful but limited.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the response shape (author, text, time) and the underlying endpoint, which is useful, but it says nothing about pagination, ordering defaults, or permissions.

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

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

Two short sentences, zero filler, with the resource and returned fields front-loaded before the endpoint reference.

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

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

With no output schema, the description helpfully discloses the returned fields, and the schema fully covers the six query parameters. Only minor gaps remain: no pagination/next_offset guidance in prose and no note on default ordering for a list endpoint.

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

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

Schema description coverage is 100% and all six parameters are documented in the schema (sort, limit, fields, offset, direction, opportunity_id), so the schema carries the heavy lifting. The description adds no parameter-level meaning beyond noting the target is an opportunity.

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 the specific resource (comments on an opportunity) and enumerates the returned content (author, text, time), so it is clearly distinguishable from the write-side sibling getfly_add_opportunity_comment. The verb 'list' only comes from the name, not the prose, so it stops short of a full 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 by the resource naming and the 'discussion' framing; there is no explicit statement of when to call this versus getfly_get_opportunity or getfly_add_opportunity_comment. No prerequisites or exclusions 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete field set and endpoint, but says nothing about auth requirements, rate limits, or result ordering beyond what the sort param already documents.

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 resource and returned fields front-loaded, then the endpoint. No filler or repetition.

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

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

For a read-only list tool with no output schema, the description conveys enough: what entities come back and which field categories they contain. Pagination mechanics are delegated to the schema, which handles them well; only response envelope details are 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% — every one of the five parameters (sort, limit, fields, offset, direction) carries its own description including defaults and the next_offset pagination hint. The description adds no parameter-level 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 (list products and services) and enumerates the data returned: code, name, category, unit, prices, VAT, dates. It also names the endpoint. It doesn't explicitly contrast with the sibling get_product, so an agent must infer list-vs-single from the verb 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?

Usage is only implied — a plural resource with pagination params signals bulk retrieval, and the sibling get_product exists for single-record fetches, but the description never says when to use this versus that or mentions any prerequisite.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely behavioral detail the annotations don't: default sort order (newest first), the set of filterable fields, and the underlying endpoint GET /api/v6.1/sale_orders.

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

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

Three compact sentences: payload contents first, then filter surface, then ordering and endpoint. Front-loaded and waste-free, though the raw endpoint string is the least useful element.

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

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

With no output schema and a nested free-form `filters` object across 9 params, listing the returned fields and the filterable field set is exactly what an agent needs to construct a useful call. Pagination and sort mechanics are left entirely to the schema, which is acceptable since it documents them at 100% coverage.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value for the open-ended `filters` object by enumerating which fields are filterable (id, order_date, created_at, updated_at) with operator hints. It says nothing extra about sort/limit/offset/fields, which the schema already documents well.

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

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

Specific verb + resource ('List sales orders') plus the exact field set returned, which lets an agent distinguish it from the single-record getfly_get_sale_order sibling. It stops short of naming that sibling explicitly, so it is 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?

'Filters: id, order_date, created_at, updated_at (eq, gte, lte, between)' and 'Newest first' imply when this listing is appropriate and how to narrow it, but there is no explicit when-to-use/when-not or pointer to getfly_get_sale_order for a single record.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the endpoint and the field set but says nothing about pagination behavior, result caps, or rate limits beyond what the schema already states.

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

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

Two compact sentences with no waste; the field inventory and endpoint come first and nothing is repeated.

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

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

With no output schema, listing the returned fields is genuinely useful and largely fills that gap. Only the absence of any note about filtering scope or total-count/pagination semantics keeps it from a 5.

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

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

Schema description coverage is 100% and each of the three parameters (limit, fields, offset) is well documented, including the next_offset pagination hint. The description adds no parameter-level meaning, 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?

A specific verb and resource ('List tasks') plus the exact fields returned and the underlying endpoint GET /api/v6.1/tasks. It clearly differs from getfly_get_task by being an enumeration, though it never names the 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?

No statement of when to use this versus getfly_get_task or a filtered lookup, and no mention that the tool accepts no filter parameters at all — an agent looking for 'tasks for project X' gets no warning that this endpoint returns everything. Usage is only implied by the verb 'List'.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the response shape (id and name) and the underlying endpoint, but says nothing about ordering, pagination, or whether categories can be empty — modest added value over the annotations.

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

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

Three short clauses, front-loaded with the resource and its fields, then the usage hint, then the endpoint. Zero filler. It is terse to the point of being fragmentary, 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-only lookup with no output schema, the description discloses the returned fields, the endpoint, and the intended follow-up action — enough for an agent to call it and use the result. Missing only minor operational details like ordering or empty-list 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?

The tool takes no parameters, so the baseline is 4. The description goes slightly further by naming the related field (cate_name) that the output feeds into, which is genuinely useful cross-tool parameter context, though not parameter semantics of this call itself.

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 the exact resource (support ticket categories) and what each entry contains (id and name), which is more than the title alone. It does not explicitly differentiate from the nearby getfly_list_ticket_statuses sibling, but the resource is unambiguous enough that an agent can pick correctly.

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

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

It gives a concrete downstream use — take a returned name and pass it as cate_name when calling getfly_create_ticket — which tells the agent not just when to call this tool but what to do with the result. No explicit exclusion against list_ticket_statuses is stated, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds a small amount of value by disclosing the returned fields (author, text, time), which matters because there is no output schema. It reveals nothing about pagination defaults, next_offset usage, or whether internal/private notes are 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?

Two short sentences with zero filler, front-loading what the tool returns and following with the endpoint. It is efficient, though the endpoint path occupies space an agent gains little 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?

For a 6-parameter paginated list tool with no output schema, the description covers only the response fields. Pagination behavior, sort semantics beyond the schema, and how this differs from get_ticket or the opportunity-comments sibling are left unaddressed, though the rich schema compensates for much of it.

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

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

Schema description coverage is 100% — sort, limit, fields, offset, direction and ticket_id all carry descriptions including defaults and the next_offset pattern. The description adds nothing param-specific, 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 the resource (comments on a support ticket) and even the fields returned, so an agent can infer it is a list/read of ticket comments. But it is a noun phrase with no explicit verb, and it offers no differentiation from the sibling getfly_list_opportunity_comments or from getfly_get_ticket. Purpose is clear but only minimally articulated beyond the title.

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 or when-not-to-use guidance, and no alternative is named. The presence of getfly_list_opportunity_comments as a sibling makes the silence notable — nothing tells the agent which comment list applies to which entity. A user must infer that this requires a ticket 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the concrete endpoint (GET /api/v6.1/tickets) and the field set returned, but says nothing about pagination behavior, rate limits, or result volume.

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

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

Two short sentences, zero filler, with the resource and returned fields front-loaded. Nothing could be removed without losing information.

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

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

For a six-parameter list tool with a nested filters object and no output schema, the description leaves return shape and pagination semantics to the schema. The schema is rich, but the description does not fully fill the gap around paged retrieval.

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 sort, direction, limit, offset, fields, and the filters object all documented including operator examples. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('List support tickets') and enumerates what is returned (code, title, content, category, customer, custom fields). It does not name sibling tools such as getfly_get_ticket or getfly_list_ticket_comments to disambiguate single-record vs. filtered-list use.

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 instead of getfly_get_ticket, getfly_list_ticket_comments, or getfly_list_ticket_statuses, and no note about pagination via offset/next_offset. The agent must infer all usage context from the schema 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 annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety behavior is covered. The description adds the return shape (id and name) and the cross-tool usage note, but does not discuss authentication, rate limits, or ordering.

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

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

Three short, front-loaded sentences with no wasted text. The return fields, usage note, and endpoint are presented efficiently.

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 parameters, no output schema, and full annotation coverage, the description supplies what is needed: the returned fields and how to use them. It omits minor details like ordering or whether all statuses are returned, but is otherwise complete for a simple lookup.

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

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

The tool has zero parameters, so the baseline is 4. There is no parameter semantics to clarify beyond the schema, and the description appropriately does not invent 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?

The description states a specific verb implicitly (listing) and resource (support ticket statuses), and specifies the returned fields (id and name). It is clearly distinguishable from siblings like getfly_list_ticket_categories and getfly_list_tickets.

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

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

It gives a concrete usage path: use a status name as status_name when creating a ticket, which links directly to getfly_create_ticket. It does not name exclusions or alternatives such as ticket categories, but the guidance is clear for a simple lookup.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context beyond that: the underlying endpoint (GET /api/v6.1/users), the identity field to reuse downstream, and the 'valid' flag semantics for active vs inactive users.

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

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

Four short, front-loaded sentences with no filler; the core purpose and the downstream usage hint come before the filter list. Slightly dense parenthetical stacking, 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?

With no output schema, the description compensates by naming the returned fields (id, name, department, email, phone). Filters, cross-tool usage, and endpoint are all covered; only pagination behavior is omitted, and the schema already documents next_offset 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds real information the open-ended 'filters' object cannot convey: the actual filterable field names (user_id, contact_name, email, contact_mobile, valid) and the meaning of valid=1. Pagination params are left to the schema, which documents them well.

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

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

States a specific verb and resource ('List the Getfly CRM users (employees)') and enumerates the returned fields, so the agent knows exactly what it gets. It is clearly distinguishable from the singular sibling getfly_get_user and from unrelated list tools like getfly_list_accounts.

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?

Adds genuine routing guidance the schema cannot: 'Use the user_name (login name) for the recipient/manager arguments of the create tools,' linking this lookup to the create_* siblings. It also names concrete filter use cases (e.g. valid=1 for active users), though it never explicitly contrasts itself with getfly_get_user.

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, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value on top with the 'WRITE:' prefix and the boundary 'without changing anything else' plus the win/loss exclusion, though it does not warn about side effects such as campaign automations firing on a stage change.

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 plus an endpoint reference. The 'WRITE:' marker is front-loaded and every clause (scope, identifiers, stage source, exclusion) 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 6-parameter mutation with no output schema, the description covers the essentials: identifiers, stage source, and what it does not change. The main residual gap is that the schema marks zero required parameters, so the agent must infer that one of the id/code pairs (and a stage value) is mandatory — implied by 'Identify the opportunity by code (or id)...' but never stated as a hard requirement.

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

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

Schema coverage is 67% and the description adds the key semantic the schema lacks: the valid values for the new stage come from getfly_get_campaign_stages, and each identifier has a code-or-id alternative. It stops short of restating field-level constraints, which the schema already handles for the code params.

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+scope: 'Move an opportunity to another stage of its campaign pipeline, without changing anything else.' This clearly distinguishes it from getfly_create_opportunity, getfly_update_account and other siblings, and even names the underlying endpoint PUT /api/v6.1/opportunity/stage.

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

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

It gives concrete usage context: identify the opportunity by code or id, the campaign by code or id, and source the new stage from getfly_get_campaign_stages. It also carves out scope ('Won/lost/cancelled results are not set here'), implying a different tool handles that outcome, but that alternative is never named.

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

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

Annotations already declare the write/destructive/idempotent profile, so the description's added value is the partial-update rule (mitigating the destructive hint) and the hard constraint that relationship/country/province names must match values pre-configured in Getfly — a failure mode not encoded anywhere in the schema. It doesn't say what happens when a name doesn't match (error vs. silent no-op) or whether omitted fields are preserved, which is the main remaining 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?

Four short sentences, zero filler, with the WRITE marker and lookup key front-loaded before the operational constraints. Every sentence carries distinct information: mode, identification, partial-update rule, value validation, exclusion list.

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 17-parameter mutation with no output schema and thin schema coverage, the description covers the highest-risk items: identification, partial update, constrained name values, and non-editable field groups. It stops short of covering failure behavior or what a successful update returns, and the majority of the 17 fields remain undocumented.

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?

At 35% schema coverage across 17 parameters, the schema leaves most fields undescribed, and the description compensates only partially: it clarifies the lookup parameter (current_account_code), the rename case (account_code), and the value-space constraint on name fields. Undescribed fields such as email, website, description, billing_address_street, and custom_fields get no semantic help from either source.

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

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

"WRITE: Update fields of an existing customer" states a specific verb (update), resource (customer), and scope (existing, field-level), and the HTTP verb/path (PUT /api/v6.1/account) pins the operation precisely. Against siblings like getfly_create_account, getfly_get_account, and getfly_list_accounts, an agent can immediately tell this is the mutation-by-lookup tool.

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?

"Send only the fields to change" defines the partial-update contract up front, and "Contacts and the type/source/industry lists are not editable here" is a concrete exclusion that redirects the agent away from fields it might otherwise guess at. What's missing is any routing advice toward a sibling (e.g., create_account for new customers, get_account to read before updating), so usage is clear but not fully comparative.

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