GoCanvas MCP by usefulapi

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

Adds real behavioral context beyond the annotations: non-idempotency ('calling twice creates two dispatches'), the push-notification side effect tied to send_notification, and the hard limit that media fields cannot be pre-filled. With destructiveHint=false and openWorldHint=true already declaring the safety profile, this is strong supplemental detail. It does not say what the response contains (e.g., the new dispatch id), 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?

Front-loaded with the 'WRITE:' marker and every clause carries information, with no filler or restatement of the title. It is delivered as one dense semicolon-chained block rather than being segmented by concern, which slightly hurts scanability.

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 12-parameter mutation with no output schema and only coarse annotations, the description covers the authoring decisions an agent must make: which type, which prerequisites, what happens without an assignee, and what cannot be pre-filled. Return shape and the less common scheduled-only parameters are left to the schema, which is acceptable given 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; the description earns above that by explaining the interaction between dispatch_type and the scheduled_* fields and by flagging the media-field exclusion for the responses array, which the schema does not state. It does not touch reminder_interval, send_calendar_invite, or department_id defaults, leaving those 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 the specific verb and resource ('WRITE: creates a dispatch') and immediately defines what a dispatch is ('a job that appears on the assignee's mobile device'), which is the key disambiguation against the read-side siblings like gocanvas_get_dispatch and gocanvas_list_dispatches. An agent can identify this as the creation path without opening the schema.

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

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

Explains the two dispatch_type branches and the conditions each imposes (immediate vs scheduled needs scheduled_at and scheduled_end), notes the optional assignee_id behavior, and points to gocanvas_get_form for entry ids. It stops short of an explicit 'use this instead of X' routing statement against siblings, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the response includes pre-filled responses, schedule and status, which is useful, but says nothing about what happens when the id is missing or unauthorized.

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 efficient, though the omitted when-to-use case means the brevity costs some guidance.

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 there is little to explain, and the description does hint at the return payload despite there being no output schema. It remains thin on error/empty behavior and on how it differs from the 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 coverage is 100% and the schema field already explains the id and its source (gocanvas_list_dispatches). The description's 'by id' adds nothing 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 resource (one dispatch) and lookup key (by id), and enumerates the payload (pre-filled responses, schedule, status), which distinguishes it from gocanvas_list_dispatches. It never names 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?

There is no explicit when-to-use or when-not-to-use guidance. 'By id' implicitly contrasts with the list tool, and the schema parenthetical points at gocanvas_list_dispatches, but the description itself offers no routing logic.

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 openWorldHint=true, so the safety profile is covered. The description adds that the response includes screens and entries with field ids and labels, but says nothing about size/rate behavior or what 'metadata' and 'minimal' actually strip out.

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

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

Two tight sentences with the resource stated first and the format guidance front-loaded. The trailing 'or "metadata" or "minimal" for less' is slightly loose but not wasteful.

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 saying what comes back, and it does identify screens and entries with field ids and labels. It is sufficient for a 2-parameter read tool, missing only the distinction between the two sparse formats.

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 genuinely adds meaning: 'flat' is framed as the required shape for reading submissions or creating a dispatch, and 'nested' is confirmed as the full-structure default. The weak spot is 'metadata' or 'minimal' for less', which does not distinguish the two enum values.

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: retrieves 'one form definition, including its screens and entries (field ids and labels).' The scope (single definition, contents included) is clear, but the description never names the sibling it complements (gocanvas_list_forms for the id, gocanvas_get_submission for the data).

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

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

'flat' is tied to concrete downstream tasks (read submissions, create a dispatch), which is useful guidance for the format choice. However, there is no explicit statement of when to call this tool versus gocanvas_list_forms or gocanvas_get_submission, so tool-selection guidance remains implied.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to establish safety. The description adds useful return-field context but does not go beyond annotations to disclose rate limits, auth requirements beyond the connected OAuth app, or other behavioral 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 two concise sentences with the resource and returned fields front-loaded, followed by a specific use case. 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 zero parameters, no output schema, and read-only annotations, the description is largely complete: it identifies the resource, lists the salient return fields, and gives a practical use. It could be slightly stronger by explicitly differentiating itself from gocanvas_get_user or by mentioning whether it returns only the current authenticated user.

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

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

There are zero parameters, so the baseline is 4. The description correctly adds no parameter semantics because none exist, and it focuses on the response shape instead.

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 identifies the resource as the user who owns the connected OAuth application and enumerates the key fields returned (id, login, company id/name, default department, role). It distinguishes itself implicitly from gocanvas_get_user by tying the resource to the 'connected OAuth application', though it does not name 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?

It provides one concrete usage context: 'Use it to learn the default department id.' However, it does not state when to use this tool versus alternatives such as gocanvas_get_user, nor does it describe exclusions or prerequisites.

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 openWorldHint=true, so the safety profile needs no restating. The one added piece of behavior is that the response includes the set's rows, which is genuine context beyond the annotations, but there is nothing about pagination, row volume, or error behavior for an unknown id.

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

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

It is one short fragment with zero waste, but this is under-specification rather than concision – there is no leading verb or scope statement to front-load, so the brevity costs clarity.

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 (1 required param, full schema coverage, annotations present), so little is needed. However, with no output schema, the description should say more about what a 'reference data set with its rows' contains to set expectations for 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?

There is a single parameter at 100% schema description coverage, and the schema already explains that the id comes from gocanvas_list_reference_data. The description adds no further meaning, so the baseline of 3 applies.

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

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

The phrase 'One reference data set with its rows' identifies the resource and its cardinality (single set, including child rows), which implicitly contrasts with the list sibling. But there is no verb, and the reader must infer from the tool name that this is a fetch operation rather than something that returns derived/aggregated data.

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

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

No guidance on when to call this versus gocanvas_list_reference_data or other get_* tools. The only routing hint ('id from gocanvas_list_reference_data') lives in the schema parameter description, not in 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine return-shape context (the response entries contain id, label, type, value), which substitutes for the absent output schema, but says nothing about not-found behavior 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. The return shape comes first and the identifier formats follow, so the most useful information is front-loaded.

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

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

For a one-parameter read tool with no output schema, the description covers what is returned at the field level and what input is accepted, which is essentially everything an agent needs to call it. Only error/not-found semantics are unaddressed.

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

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

Schema description coverage is 100%, and the schema already documents both acceptable forms (numeric id or client GUID) with examples. The description restates the dual-format acceptance without adding new syntax or constraint detail, so it matches the 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?

The description states a specific resource ("one submission with all its responses") and enumerates the response fields it returns (entry id, label, type, value). The word "One" implicitly distinguishes it from gocanvas_list_submissions, 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?

Usage is only implied: fetch a single submission by id. There is no explicit statement of when to use this versus gocanvas_list_submissions or gocanvas_list_submission_revisions, and no mention of what happens if the id is unknown.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context by listing which user attributes come back, which matters since there is no output schema. It says nothing about error behavior for invalid or unknown ids.

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

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

A single compact fragment with the scope front-loaded and the returned fields following, with no wasted words. It reads as a label rather than a sentence, which slightly weakens readability but not economy.

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

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

For a single-parameter read tool with annotations covering safety, this is nearly sufficient: identity, scope, and returned fields are all stated. Only failure modes and pagination/format expectations, which are minor here, 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%, and the schema itself documents the sole user_id parameter including its source (gocanvas_list_users). The description adds no additional semantics about the id beyond what the schema already states, so the baseline of 3 applies.

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

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

States the resource and scope precisely ('One user by id') and enumerates the fields returned (name, login, contact data, department, role), which lets an agent distinguish it from gocanvas_list_users and gocanvas_get_me. The verb is implicit in the fragment rather than stated, keeping it 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?

The description gives no when-to-use guidance and names no alternatives, despite close siblings like gocanvas_list_users and gocanvas_get_me. The only routing hint ('from gocanvas_list_users') lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds the useful behavioral detail that results are paged and that a customer may or may not be attached to a site, but says nothing about volume, filtering limits, 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 short, front-loaded sentences with the entity definition first and the paging note last; nothing is padded. It is terse to the point of being slightly elliptical, but every clause carries 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 simple read-only single-parameter list tool this is close to sufficient, and pagination is handled by the schema. However, with no output schema the description never indicates what fields a customer record contains, which is the main remaining gap for an agent deciding whether this call answers its question.

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 'page' parameter is thoroughly documented there, including the 100-per-page size and the next_page idiom. The description's 'Paged' only restates that. Baseline 3 applies since 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?

Defines the resource precisely as 'Customers (contacts of the Project Management view)' and distinguishes it from adjacent entities like users and sites by naming the view it belongs to. The listing action itself is only carried by the tool name, not the description text, so it stops short of a full verb+resource statement.

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 guidance and no reference to any of the many siblings (gocanvas_list_users, gocanvas_list_sites, gocanvas_get_reference_data) that an agent could confuse this with. 'Paged' hints at iteration but nothing states prerequisites or 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 and openWorldHint=true, so safety is covered. The description adds a genuinely non-obvious behavioral detail: the synthetic department -1 'All' is included in the results, which prevents an agent from misinterpreting or double-counting it. It does not discuss result ordering or limits, but for a 0-param lookup that is minor.

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

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

Two short sentences with nothing extraneous. The returned-field list comes first and the caveat about -1 follows, both front-loaded and easy to scan.

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 describing the response, and it does give the three fields plus the synthetic -1 entry. It stops short of stating whether the list is paginated or sorted, but for a simple reference-data list that is a modest 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 the baseline is 4; there is nothing for the description to disambiguate. The field list describes output rather than input, which is a reasonable substitute given no output schema exists.

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 identifies the resource (company departments) and enumerates the returned fields (id, name, description), which lets an agent tell it apart from gocanvas_list_department_users or gocanvas_list_groups. It lacks an explicit verb, but combined with the title 'List GoCanvas departments' 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?

There is no explicit statement of when to call this versus alternatives (e.g., to resolve a department id before calling gocanvas_list_department_users), so usage is only implied by the resource name. The note about the -1 'All' pseudo department is the closest thing to actionable guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results include each user's department role, which is useful output context, but it omits pagination behavior, permissions requirements, and return shape details.

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 compact sentence with no wasted words and the key scope (one department, department role) is front-loaded. It is efficient, though its brevity contributes to gaps in usage guidance.

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 list tool with full schema coverage and safety annotations, the description is minimally adequate. It still leaves out routing versus gocanvas_list_users, pagination expectations, and any sense of result volume or format.

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 department_id parameter is fully documented in the schema, including its source from gocanvas_list_departments. The description adds no further parameter semantics beyond indicating that exactly one department is involved, so the baseline of 3 is appropriate.

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

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

The description names a specific resource (users in one department) and adds useful scope detail (department role), making the core purpose clear. However, it does not explicitly differentiate this from sibling gocanvas_list_users or state the list verb beyond what the title already provides.

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 gocanvas_list_users, gocanvas_get_user, or gocanvas_list_departments. Usage is only implied by the required department_id parameter in 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 readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the mandatory-filter rule and that results are paged, but says nothing about page size (only in schema), next_page chaining, or behavior on an empty/invalid filter set.

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 definition, then the hard constraint, then format and paging. No filler and nothing repeated from the schema verbatim.

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 10-parameter, no-output-schema list tool, the description is serviceable but thin: it omits how paging works (next_page from the prior reply), the special 'ready' status semantics, and any sense of result volume. The mandatory-filter rule is the one piece of real added value.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's one addition is the cross-parameter constraint that at least one of user_id, department_id, or form_id must be supplied — helpful, but the ISO-8601 note merely restates the schema's pattern and loses to the schema's clearer status semantics (ready ignores date filters).

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 and defines it parenthetically ('jobs sent to field workers'), then enumerates the fields returned, which distinguishes it from gocanvas_get_dispatch (single record) without naming that sibling explicitly. The verb 'list' is only implied via the tool name and the field enumeration.

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 real filter precondition ('At least one of user_id, department_id or form_id is required'), which is genuinely useful since the schema marks zero parameters required. However, it gives no routing guidance against siblings like gocanvas_get_dispatch or gocanvas_list_submissions, leaving when-to-use largely inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are report definitions with an emailed-by-default flag and that results are paged, but it doesn't state ordering, whether an empty list is possible, or what a caller gets when the form has no reports.

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 no filler, and the key identity of the resource is front-loaded. The trade-off is that the telegraphic fragment style omits an explicit verb, making it slightly less readable than a full sentence would be.

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 small read-only listing tool with full schema coverage and an annotation-declared safety profile, this is nearly sufficient. Because there is no output schema, the field enumeration (id, name, format, emailed default) usefully compensates, though the relationship to sibling form/report tools remains unstated.

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 form_id and page are fully documented in the schema, including the 1-based paging and 100-per-page behavior. The description adds nothing parameter-specific 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?

Names a specific resource — the report/PDF definitions attached to a form — and enumerates the fields returned, which clearly separates it from get_form and the other list_* tools. The verb is only implied by the fragment phrasing rather than stated, so it falls just short of a full verb+resource statement.

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 versus gocanvas_get_form or gocanvas_list_forms, no prerequisites (e.g. that form_id must exist), and no exclusions. An 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 mark this readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: results are paged at a fixed 100 per page and are limited to what the connected user can see. It stops short of describing the paging envelope (next_page) explicitly, 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 resource and scope, then the sibling alternative. Every clause carries information: scope, returned fields, paging, and the routing hint.

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 lists the fields returned, and it covers paging behavior. It could go slightly further on the page-token reuse and the assigned-flag semantics, but for a simple two-parameter list tool this is close to 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 both parameters (page, assigned) are already documented in structured form. 'Paged, 100 per page' mostly repeats the schema's own text and the description says nothing extra about the `assigned` flag, 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 names a specific resource ('Forms (mobile form definitions)') with an explicit scope ('the connected user can see') and enumerates the returned fields (id, name, status, version, department). The final clause explicitly separates it from the sibling gocanvas_get_form, so an agent can pick the right tool without opening a schema.

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

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

It states the use case (finding forms the user can see) and routes the agent to the sibling tool when detail is needed: 'Use gocanvas_get_form for a form's fields (entries).' That is an explicit alternative plus the condition that selects it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds that results are paged and that assigned forms/users are embedded in each record, which is useful shape information, but it says nothing about permissions, result caps, or total counts.

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 telegraphic fragments with zero padding, and the payload contents are front-loaded. It is efficient, though the near-noun-phrase style leaves the actual action implicit.

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 no output schema, the field enumeration is the right kind of compensation. Still missing are whether all groups are returned or scope-filtered, and whether elevated permissions are required to see group membership.

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 'page' parameter, including the 100-per-page size and the next_page hint, so the schema does the heavy lifting. 'Paged' in the description reinforces but does not extend 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?

The fragment names the resource (user groups) and enumerates the returned fields (id, name, forms and users assigned), so an agent knows exactly what it gets back. It does not distinguish itself from adjacent list tools such as gocanvas_list_department_users or gocanvas_list_users, which is the main clarity gap.

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 the many sibling list tools, and no prerequisites or exclusions. 'Paged' only hints at the paging workflow, which the schema already documents.

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 and openWorldHint, so safety is covered; the description adds the feature-flag dependency and the 7-day maximum window, both of which constrain whether a call will succeed. It omits what a location record contains and how paging terminates beyond 'Paged', 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?

Four short sentences, zero filler, with the resource and prerequisite front-loaded and the constraint/scope notes after. The opening is a bare noun phrase rather than a sentence, which slightly weakens the lead, but 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 read-only, 5-parameter, fully documented list endpoint with no output schema, the description covers the essentials an agent needs: prerequisite, required window, span cap, scope control, and pagination. The only material gap is that it does not say what fields a location event returns, which matters somewhat since 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 coverage is 100%, so the baseline is 3. The description still earns credit by explaining the behavioral consequence of omitting user_id (returns all company users) rather than just its literal meaning, and by restating that both dates are required and capped at a 7-day span. It says nothing about use_created_at, which the schema already handles.

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 identifies a specific resource — GPS location events of field users — and pairs it with the tool name's 'list' verb, so the agent knows it retrieves location records. It also names the gating prerequisite (tracker feature). It stops short of an explicit verb+scope sentence, but no sibling tool competes for this resource, so disambiguation is not a concern.

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?

'Needs the tracker feature' is a real precondition, and 'Omit user_id for all users of the company' tells the agent how to widen scope. However, there is no explicit when-to-use/when-not framing and no routing to alternatives (e.g., whether gocanvas_get_submission or list_submissions is preferable when the goal is a specific record's location).

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 openWorldHint=true, so the safety profile is covered. The description adds the one behavioral fact that results are paged, which is genuinely useful because pagination affects how the agent calls the tool. It says nothing about how many results come back, how next_page works, or what happens on the last page; the schema's page description carries that information instead.

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 two short non-repetitive fragments with no filler, and the resource is named before the pagination note. The terseness comes from missing content (contextual completeness) rather than from wasted wording, so it scores well here.

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 explain what a "project" contains and roughly what a caller gets back, but it does not. It never says whether the Project Management view is a separate product area or requires specific access, which is critical context for a tool that is open to the world. For a resource the agent likely does not know, the description is too thin.

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 parameter, so the schema already explains the 1-based page numbering, the 100-results-per-page size, and the next_page handoff. The description does not add anything beyond "Paged", which the schema's page description already states more precisely. That makes the baseline of 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?

The description names the resource ("Projects of the Project Management view") but never states the verb explicitly; the reader has to rely on the tool name to know this is a list operation. It gives a hint of scope (the Project Management view) that marginally separates it from the list_users or list_forms family, but it is close to restating 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?

The only usage signal is the word "Paged", which tells the agent the results are paginated but not when to choose this tool over alternatives, nor what prerequisites exist (auth, role, or view access). No exclusions or alternative tools are mentioned, and none of the many list_* siblings are referenced.

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 openWorldHint=true, so the safety profile is covered. The description adds a genuine behavioral rule not present in the schema: the department scoping falls back to the user's default department when department_id is omitted, which changes what results come back.

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

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

Two short, front-loaded clauses with no filler; the parenthetical gloss on 'reference data' earns its place for agents unfamiliar with GoCanvas terminology. It is terse to the point of being fragmentary, which slightly hurts readability.

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 return fields is helpful, and the department default is covered. But for a list tool with a near-identical get sibling, the description leaves the agent without a clear selection rule and says nothing about filtering semantics of the assigned flag.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above baseline by explaining the default behavior of department_id, which the schema only labels as 'Department id.' It does not add anything about page or assigned, but those are already well documented.

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 defines the resource precisely as reference data / lookup tables used by forms and enumerates the returned fields (id, name, columns, version). However, the verb is only implied, and it does nothing to separate this from the sibling gocanvas_get_reference_data, which an agent could easily confuse with 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?

'Without department_id the user's default department is used' gives one useful calling rule, but there is no statement of when to use this list tool versus gocanvas_get_reference_data or the other list_* siblings. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds that results are paged, which is genuine behavioral context, but says nothing about the shape of returned sites, how to detect the last page, or rate/limit behavior.

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

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

Two short fragments with zero redundancy, and the resource identity is front-loaded before the pagination note. It leans toward terseness rather than padding, so it earns credit for efficiency rather than being penalized.

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 this is minimally viable: the agent knows what it lists and that it paginates. With no output schema, the description should have said what a site record contains and how pagination terminates, which it omits.

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 optional parameter and the schema documents it fully (1-based, max 100000, 100 results per page, use next_page from the previous reply). With 100% schema coverage the schema does the work, and the description contributes only the word 'Paged', 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 names the resource ('Sites (job locations)') and scopes it to the 'Project Management view', which is more specific than the title. However, it is a bare noun phrase with no verb, and it does not distinguish this tool from the very similar sibling gocanvas_list_locations or from gocanvas_list_projects, leaving the agent to guess which list of locations is intended.

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 sibling is named as an alternative despite gocanvas_list_locations and gocanvas_list_projects existing. The only usage signal is the trailing 'Paged.', which implies iteration but not selection criteria.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds useful context that results include who changed the submission and when, and that the output is paged, but does not discuss rate limits or error 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?

Two compact sentences with no filler, front-loading the resource and its content before the pagination note. Every phrase 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-only list tool with complete schema coverage and no output schema, the description provides enough: what is returned (who changed it and when) and that results are paged. Minor gaps around return format are acceptable given the simplicity.

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

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

Schema description coverage is 100%, so both submission_id and page are fully documented in the schema, including pagination defaults and next_page usage. The description's word 'Paged' adds nothing 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?

The description names a specific resource — a submission's revision history — and clarifies its content as who changed it and when. It is clearly distinct from gocanvas_get_submission, though it does not explicitly reference 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?

There is no statement of when to use this tool versus alternatives such as gocanvas_get_submission or gocanvas_list_submissions, and no prerequisites or exclusions. Usage is only implied by the tool's purpose.

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 and openWorldHint, so safety is covered; the description adds pagination behavior (100 per page, paged), the default status filter, and the mandatory-filter constraint. It does not mention rate limits, auth scope, or ordering of results, so it stops short of full behavioral disclosure.

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

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

Front-loaded with the resource and returned fields, then constraints, then the alternative tool — a sound ordering. The telegraphic fragment style ('Completed forms (submissions): id, form, number...') is dense but every clause carries information.

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

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

For a 10-parameter list tool with no output schema, the description covers returned fields, pagination, defaults, and filter prerequisites. Minor gaps remain (e.g. behavior with status=all, whether department_id interacts with user filters) but nothing that would cause a mis-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?

With 100% schema coverage the baseline is 3, but the description adds real cross-parameter semantics the schema cannot express: the at-least-one-of requirement and the mutual exclusion of user_id/user_email. It also clarifies that dates filter created_at, which sharpens start_date/end_date intent.

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 the resource (completed forms/submissions), enumerates the returned fields, and explicitly routes detail retrieval to gocanvas_get_submission. An agent can distinguish this from the sibling getter without consulting either schema.

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

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

Gives an explicit precondition (at least one of form_id, user_id or user_email), an incompatibility rule (user_id and user_email cannot be combined), a default (status=completed), and names the alternative tool for answers. Nearly nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the pagination behavior (100 per page), which is useful context beyond annotations, but says nothing about rate limits, ordering, or total-count behavior for a paged external API.

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

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

Two short, front-loaded sentences with zero filler and the returned-field list up front. It is efficient but leans so terse that key usage guidance is omitted rather than merely compressed.

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, enumerating the returned fields (id, name, email, enabled) is a valuable addition, and pagination is covered. But for a company-wide list tool with multiple listing siblings, the absence of any disambiguation or filtering guidance (e.g., company vs department scope) leaves a real gap.

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

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

Schema description coverage is 100%, so both parameters (page, enabled) are already fully documented, including the enabled filter default and the page/next_page semantics. The 'Paged, 100 per page' phrase merely restates schema content rather than adding new 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?

States a specific verb+resource (lists company users) and enumerates the fields returned (id, name, email, enabled), which lets an agent distinguish it from single-user and department-scoped siblings implicitly. However, it does not name those siblings (gocanvas_get_user, gocanvas_list_department_users) to make the scope contrast 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?

The only guidance is 'Paged, 100 per page', which is retrieval mechanics, not when to select this over get_user or list_department_users. There is no statement of when-not to use it or which alternative to prefer for department-scoped vs company-scoped queries.

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 openWorldHint=true, so the safety profile is covered. The description contributes genuinely new behavior: results are restricted to the connected user's participation, and each entry carries handoff states plus a count of claimable tasks — useful signals that the annotations cannot convey. It stops short of describing ordering or empty-result 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?

Two sentences, both earning their place: the first defines the resource and its scope, the second covers response content and pagination. The scope constraint is front-loaded so an agent sees the key limitation immediately.

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

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

For a single-optional-param read tool with no output schema and annotations covering read-only safety, this is close to complete: it explains the domain entity, the visibility filter, and the notable payload fields. Only minor gaps remain, such as result ordering and behavior when the user has no workflows.

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 'page' parameter is fully documented in the schema, including the next_page usage pattern and the 100-results-per-page size. The description's only contribution is the word 'Paged.', which adds nothing 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 gives a specific resource (workflows) with an inline definition of the domain term ('handoff chains between users') and an explicit scope: workflows the connected user takes part in. That scoping distinguishes it from list-style siblings such as gocanvas_list_dispatches, though it never names an alternative explicitly.

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

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

Usage is implied by the scope clause ('the connected user takes part in') and by the promise of task counts ('tasks available to claim'), which hints at a work-queue use case. There is no explicit when-to-use guidance, no exclusions, and no pointer to a sibling when the user needs workflows they do not participate in.

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

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

Goes well beyond the annotations by disclosing the auth/assignment requirement, the exact state transition, and that a repeat call is refused by GoCanvas. The refusal-on-repeat is in mild tension with idempotentHint=true, but it is a refusal of a redundant no-op rather than a contradicting effect, so it reads as added context rather than a contradiction. It does not state 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?

Two compact clauses with zero filler, and the operation class ('WRITE:') plus the effect are front-loaded before the preconditions.

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 write tool with no output schema, the description covers the critical facts: it mutates, what state it requires, and how repeats behave. The only missing piece is whether the call returns anything the agent can rely on.

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

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

Schema coverage is 100% and the single dispatch_id parameter is fully documented in the schema, so the description carries no additional burden. It refers to 'a dispatch' generically and adds no format or lookup 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?

States a specific verb (acknowledges/marks received), the resource (a dispatch), and the resulting state change (status becomes received), prefixed with 'WRITE:' so the mutation class is unambiguous. This clearly separates it from get_dispatch and list_dispatches siblings.

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

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

Gives explicit preconditions: the dispatch must be in the 'assigned' state and assigned to the connected user. That tells the agent when the call will succeed, though it does not name an alternative (e.g., get_dispatch to verify state first) or say what to do on failure.

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