UserVoice MCP by usefulapi

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

Annotations already flag this as a non-read-only, destructive, open-world write, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot convey: the comment is public on the portal, subscribers are emailed, and it can be posted on behalf of another user by email. It does not mention auth/permission requirements or rate limits, keeping it short of 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 dense sentences with the write/public nature front-loaded, the sibling disambiguation second, and the endpoint last. No filler, 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 4-parameter write tool with no output schema, the description plus annotations plus full schema coverage give the agent everything needed: the effect (public comment, emails sent), the impersonation option, and the alternative tool. Nothing material 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 all four parameters are documented in the schema, and the baseline is 3. The description only restates the user_email capability already covered by the schema ('on behalf of a user (by email)'), adding no format or edge-case detail beyond it.

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 precise verb and resource ('post a PUBLIC comment on a suggestion') plus its scope ('visible on the portal and emailed to its subscribers'), and explicitly distinguishes itself from the sibling uservoice_add_note. An agent can pick this tool over the near-identical note sibling 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?

Gives an explicit when-to-use-this-vs-alternative rule: 'For an admin-only remark use uservoice_add_note.' The contrast between public comment and admin-only note is exactly the disambiguation an agent needs among these siblings.

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=false, and openWorldHint=true. Beyond that, the description adds real behavioral value: the POST endpoint and the non-obvious side effect that linking to a suggestion "adds that user's support." This side effect is not derivable from 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?

One dense sentence, front-loaded with the "WRITE:" tag and the core action, ending with the endpoint. Little waste, though the clause stacking makes it slightly heavy.

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?

No output schema exists, so the description carries return-value burden; for a create it defers reasonably to the endpoint. It covers the write, the side effect, and the endpoint, but could mention reversibility given destructiveHint=true.

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 body/source_url/user_email/suggestion_id are already documented. The description adds the semantic that suggestion_id linkage also confers the user's support, but otherwise restates the schema fields at the baseline level.

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 ("capture"/WRITE) and resource ("a piece of customer feedback"), and clarifies the two optional linkages (user by email, suggestion). It implicitly distinguishes itself from add_comment/add_note/add_suggestion by describing feedback capture rather than naming a sibling explicitly.

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

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

The parenthetical "(for example from a call or ticket)" hints at when this applies, but there is no explicit when-not guidance or named alternative among the many sibling write tools. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the write/mutability profile is covered. The description adds non-annotation context that matters: admin-only authorization, end-user invisibility, and the concrete endpoint POST /api/v2/admin/notes. It does not explain the destructiveHint, though for an append-style note creation there is little to disclose beyond this.

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, front-loaded with the 'WRITE:' signal and then the key constraint (admins only, invisible to end users), closing with the endpoint. No filler or redundancy.

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

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

For a 3-parameter write tool with no output schema and annotations that already carry the safety profile, the description covers operation, audience, visibility and endpoint — enough to call it correctly. Missing only minor details such as error behavior or whether the note body is rendered as plain text (that lives in 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% — suggestion_id, body and parent_note_id are each documented in the schema. The description echoes the optional reply relationship ('optionally as a reply to another note') but adds no format, constraint or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (add) and resource (internal note on a suggestion), plus the scope qualifiers that separate it from siblings: 'admins only, never shown to end users'. An agent can distinguish this from uservoice_add_comment (public comment) without opening 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 clear context for use: an internal, admin-only note attached to a suggestion, optionally threaded as a reply. The visibility restriction implicitly routes public-facing responses to uservoice_add_comment, but no sibling is named explicitly and there is no explicit when-not 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=false and idempotentHint=true, so the 'WRITE:' prefix and the idempotency note largely restate structured data. The POST endpoint path is a small addition, but nothing is said about permissions, the effect on the suggestion's existing labels, or rate limits.

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 tight sentence, front-loaded with 'WRITE:' so the mutation nature is visible immediately. No filler, though it is minimal to the point of leaving gaps.

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 write with annotations already covering the safety/idempotency profile and full schema descriptions, the definition is adequately complete. Only permission requirements and the exact effect on suggestion state are missing, which are minor here.

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

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

Schema description coverage is 100%, so both parameters (label_id, suggestion_id) are already documented, including the pointer to uservoice_list_labels. The description adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: 'attach a label to a suggestion,' which clearly separates it from siblings like add_comment or add_feedback. It does not explicitly name a sibling it should be preferred over, but the action 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?

The clause 'attaching it again changes nothing' gives a reuse condition, implying safe repeat calls, but there is no explicit when-to-use vs when-not, no prerequisites, and no named alternative (e.g., detach or list). 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 the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true). The description adds value beyond them: it discloses the side effect that a user is created if the supplied email is new, that the suggestion becomes visible on the portal, and the underlying endpoint. Return behavior is the only notable gap.

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

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

A single densely packed sentence, front-loaded with the 'WRITE:' marker and the core action, with no wasted words. Optional and side-effect details follow in logical order.

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

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

For a mutation tool with full schema coverage and annotations carrying the safety profile, the description covers creation scope, byte-level side effects, and endpoint. It does not say what is returned (e.g. the created suggestion/id), which with no output schema is a minor remaining gap.

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

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

Schema coverage is 100%, so the schema already documents all six parameters (baseline 3). The description nonetheless adds meaning beyond the schema by explaining the creator_email semantics ('user is created if new'), which the schema does not state.

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

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

States a specific verb (create) and resource (suggestion/idea) plus scope (in a forum, optionally in a category). It clearly distinguishes itself from read siblings like uservoice_get_suggestion and uservoice_list_suggestions.

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 signals the operation class and implies usage, but the description never names an alternative or states when this tool is preferable to sibling create/add tools (e.g. uservoice_add_feedback, uservoice_add_comment). Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the underlying endpoint (GET /api/v2/admin/subdomains/current) and the credential-scoping insight, which is useful but modest additional context beyond the annotations.

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

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

A single front-loaded sentence that names the resource first, then the returned fields, then the endpoint. Nothing is padded and 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?

With no output schema, the description usefully enumerates the returned fields (id, name, default forum, settings), which partially compensates. For a zero-parameter read-only call with full annotation coverage, this is nearly 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?

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter surface for the description to explain, and nothing is ambiguous about 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?

States the specific resource (the UserVoice account/subdomain tied to the current credentials) and enumerates what it returns: id, name, default forum, and settings. The verb is only implicit via the title 'Get account', but the resource is precisely identified. Siblings are unrelated resources so no differentiation is needed.

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 this to discover which account/subdomain your credentials belong to — but there is no explicit when-to-use statement, no prerequisites, and no named alternatives. An agent can infer the context but the description does not say so directly.

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 that related records can be sideloaded and notes the admin API endpoint, but says nothing about return shape, not-found behavior, or auth requirements beyond the admin path.

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

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

Two short sentences with zero waste; the core purpose and the optional sideload behavior are 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?

For a simple single-record GET with full schema coverage and annotations carrying the safety profile, the description is nearly sufficient. The absence of an output schema means it could say more about the sideloaded `included` payload, but nothing essential for invocation 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 documented in the schema, including the `included` sideload target. The description's enumeration of related record types (forum, category, status, labels, users, status updates) merely restates the includes enum and adds no syntax or format detail beyond it.

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

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

States a specific verb and resource with singular scope: 'One suggestion (idea) by id, optionally with related records.' The word 'One' implicitly distinguishes it from the sibling list_suggestions, but it never names that sibling, so differentiation is left to inference.

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

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

Usage is only implied – retrieving a single record by id suggests fetching a known suggestion, versus list_suggestions for browsing. There is no explicit statement of when to prefer this tool, no prerequisites, 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=true, destructiveHint=false and openWorldHint=true, so safety is covered by structured data. The description's only additional signal is the '/api/v2/admin/...' path, which weakly hints at elevated admin permissions, but it says nothing about auth requirements, error behavior on a missing id, or rate limits. Minimal value beyond the annotations.

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

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

Two very short sentences with the core purpose front-loaded and no filler. The second sentence (raw endpoint path) adds marginal value for an agent, but the brevity is not a defect.

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 lookup with no output schema, the description is adequate but thin: it does not indicate what the response contains (user fields, permissions visibility) or what happens when the id does not exist. An agent can call it correctly, but the result contract is left to inference.

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% (user_id is documented with type constraints), so the schema carries the parameter meaning. The description's 'by id' restates rather than extends it — no format, sourcing, or lookup guidance is added. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource (get one user) and constrains it by id, which distinguishes it from the sibling uservoice_list_users without the agent needing to open a schema. It is clear but does not name the 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 only implied: 'One user by id' suggests this is the single-record lookup versus the list variant, but there is no explicit when-to-use, when-not-to-use, or named alternative. Nothing is misleading, but nothing routes the agent either.

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 safe-read profile is covered. The description adds that this is the admin API surface and supports forum scoping, but discloses nothing about permissions, pagination behavior, or ordering defaults beyond what annotations and schema 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?

Two short sentences, front-loaded with the core action and followed by the endpoint reference. Efficient with no filler, though the trailing endpoint string is of marginal value since no output/return information accompanies it.

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

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

A simple read-only list tool with full schema coverage needs only light description support, and the core purpose is conveyed. It stops short of noting the admin scope's permission implications or default sort behavior, leaving minor gaps for an agent that must 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 description coverage is 100%, so all five parameters (page, sort, cursor, per_page, forum_ids) are fully documented in the schema. The description restates forum scoping but adds no syntax or format detail, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List suggestion categories') and the endpoint, which is clear. It doesn't explicitly differentiate from sibling list tools like uservoice_list_forums or uservoice_list_suggestions, but the resource is named precisely enough to be distinguishable.

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?

'optionally only those of some forums' implies you can scope the list by forum, which hints at usage context. However, it gives no explicit when-to-use vs alternatives, no prerequisites, and no guidance on when to reach for this over a sibling list tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying admin endpoint path, which is mildly useful context, but says nothing about pagination behavior, result ordering, or volume limits.

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

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

Two short sentences, front-loaded with the core action and followed by the optional scoping. The trailing raw endpoint path is mildly redundant but not disruptive; nothing is padded.

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

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

For a read-only, fully-schema-documented list tool with no required parameters, the description covers purpose and filtering adequately. It omits pagination/ordering guidance, though the schema supplies cursor and sort semantics, and there is no output schema to explain.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (including cursor-vs-page preference and per_page bounds). The description only restates two of the eight filters (suggestion_ids, state) and adds no format or interaction detail, 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 clear verb+resource ('List public comments') and names the two optional filter axes (suggestions, moderation states) that map to real parameters. It doesn't need to distinguish from a sibling because no other list-comments tool exists, but it also doesn't position itself against the many other list_* 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?

The phrase 'optionally only those on some suggestions or in some moderation states' implies when the filters are useful, but there is no explicit guidance on when to use this versus e.g. uservoice_list_notes or uservoice_list_suggestions, and no stated 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 cover safety (readOnlyHint, destructiveHint=false, openWorldHint), so the burden is lower; the description still adds that results carry suggestion counts and supporter revenue and that the call hits the admin endpoint /api/v2/admin/features, a useful auth-privilege signal. It stops short of rate limits or pagination caveats, but it goes beyond the annotations.

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

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

Three short sentences, no waste: scope first, then filtering, then the underlying endpoint. Information 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?

With 7 optional params all covered by the schema and no output schema, the description usefully discloses the shape of returned data (counts and supporter revenue) and the filter dimensions. Minor gap: no mention of pagination behavior for large result sets, though cursor/per_page are covered in-schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in-schema — the baseline of 3 applies. The description only restates the filter axes (text, suggestion, product area) without adding format, combination, or precedence rules 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 (List) plus resource (product features), with a clarifying parenthetical that defines a 'feature' as the roadmap item suggestions link to — which cleanly separates it from uservoice_list_suggestions and the other list tools. The description also names the returned payload scope (suggestion counts, supporter revenue).

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 three filter axes (text, linked suggestion, product area), which implies when the tool is useful, but there is no explicit 'use this instead of X' routing against siblings like list_suggestions or list_categories, and no 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, destructiveHint=false, openWorldHint=true, so the safety profile is covered and the bar is lower. The description still adds value by naming the underlying endpoint (GET /api/v2/admin/feedback_records) and disclosing that records originate from multiple channels, both of which help the agent reason about result shape.

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

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

One tight sentence plus the endpoint, with the core action front-loaded. The parenthetical source list is slightly long but genuinely informative and placed after the main clause, so little 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 and no required parameters, the description plus the fully-documented schema and read-only annotations give the agent enough to call this correctly. Pagination, sort, and time-window semantics live in the schema, so their absence from the prose is a minor gap rather than a hole.

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

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

Schema description coverage is 100%, so all eight parameters (page, cursor, per_page, sort, user_ids, suggestion_ids, updated_after/before) are already documented in the schema. The description only restates the suggestion/user filter idea and adds no format or syntax detail beyond it, 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 ('List') and resource ('captured feedback records'), and enumerates the sources records come from (admin console, widget, Zendesk, Salesforce, Slack, API). It does not name a sibling tool or contrast itself with one, but the resource is unique among the siblings (which list suggestions, users, comments, etc.), so an agent can place it.

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

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

The phrase 'optionally only that linked to some suggestions or users' implies the filtering use case, but there is no explicit when-to-use/when-not guidance, no prerequisite (e.g. permissions), and no routing to alternatives such as uservoice_list_suggestions or uservoice_get_user. 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the return contents (name, open/private state, suggestion counts) and the GET endpoint, but discloses nothing about pagination behavior beyond what the schema shows.

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

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

Two compact sentences with the resource and returned fields front-loaded and no wasted prose. The trailing 'Use a forum id...' clause is mildly extraneous given no such parameter exists 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?

With no output schema, the description partially compensates by naming the returned fields, and the schema carries pagination. However, a bare list tool with no stated ordering default or result-size behavior leaves the agent relying entirely on structured fields.

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

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

Schema description coverage is 100% with all five filter/pagination params fully documented, so the baseline is 3. The description adds only a passing mention of a 'forum id', which is not actually a parameter of this tool and risks confusing the agent.

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

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

States a specific verb+resource ('List the feedback forums (idea portals)') and even enumerates the returned fields. It is distinguishable from list_categories/list_suggestions by the 'forums' resource, though it does not explicitly contrast itself with those 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?

The only guidance is 'Use a forum id to filter or create suggestions,' which describes downstream use of the returned ids rather than when to call this tool versus the many other list_* siblings. No prerequisites, exclusions, or alternative-routing is 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 usefully adds the concrete endpoint GET /api/v2/admin/labels, hinting at admin-scoped access, but says nothing about pagination behavior, rate limits, or result shape.

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

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

Two short sentences: purpose first, endpoint second. Nothing is wasted and it is properly 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?

With no output schema, the description could have said what a label record contains or how results are returned, but it stays silent. For a simple read-only list tool with fully documented parameters and safety annotations, this is adequate but not 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 page, sort, query, cursor and per_page are all documented in the schema itself. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb ('List or search') and resource ('labels used to organize suggestions'), which is enough to separate it from list_categories and list_statuses. It does not explicitly name those siblings, 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?

The phrase 'List or search' implies the query parameter drives a search mode, and the admin endpoint is disclosed, but there is no explicit when-to-use, when-not-to-use, or alternative tool guidance. Usage must be inferred from 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, destructiveHint=false and openWorldHint=true. The description adds genuinely useful non-annotation context: these are internal admin-only notes (an authorization requirement) and the underlying endpoint. Pagination/sort behavior is left to the schema.

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

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

A single front-loaded sentence stating the resource, scope, filter option, and access restriction, followed by the endpoint path. No filler.

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

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

For a fully-optional, 7-parameter read tool with 100% schema coverage and no output schema, the description covers purpose, access level, and the key filter. Return shape and pagination mechanics are not addressed, but the schema handles those adequately.

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 seven parameters (page, cursor, sort, per_page, suggestion_id, updated_after/before) are fully documented in the schema. The description only nods at the suggestion_id filter, adding no syntax or semantics 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?

Specific verb+resource ('List internal (admin-only) notes') with a scope qualifier ('optionally only those on one suggestion'). This clearly separates notes from the sibling list tools like uservoice_list_comments and uservoice_list_supporters, though it doesn't name those siblings explicitly.

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

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

'Optionally only those on one suggestion' implies the filtering use case, but there is no explicit when-to-use guidance versus alternatives such as list_comments or list_feedback_records, and no prerequisites stated beyond the admin-only hint.

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 useful context by naming the underlying endpoint (GET /api/v2/admin/statuses) and the returned shape, but says nothing about pagination, rate limits, or the public-vs-admin scope tension hinted by the path.

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 padding, with the resource definition front-loaded and the endpoint reference last. Every sentence carries distinct 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?

With no output schema, the description usefully names the returned fields and gives example status values, and pagination is fully covered by the schema. Only the somewhat unusual admin endpoint behind a 'public statuses' listing goes unaddressed, a minor 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%: page, sort, cursor and per_page are all documented in the schema itself (cursor noted as preferred over page). The description contributes no parameter guidance, 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 the public suggestion statuses'), enumerates concrete examples, and describes the returned fields (ids, colors, open/closed flag). The precise 'statuses' naming separates it from the nearby sibling uservoice_list_status_updates without opening 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?

The sentence 'Use the ids for filters and status updates' implies downstream usage and positions the tool as a lookup prerequisite, but it never states when to call this instead of the many sibling list tools, nor any exclusions. Usage is implied rather than instructed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context by listing the returned fields and noting the admin API path (GET /api/v2/admin/status_updates), which hints at the privilege scope, but it says nothing about pagination behavior 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?

One sentence plus the endpoint path; the field enumeration is packed into a parenthetical rather than padded prose. Nothing is wasted and the resource scope 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?

With no output schema, the description's enumeration of returned fields is valuable and largely compensates. Pagination is handled by the schema's cursor/page params, though the description could note that results are paginated and that suggestion_ids narrows scope further.

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 7 well-documented parameters (cursor preferred over page, per_page default 20, sort syntax, date filters), so the schema carries the full parameter burden. The description adds no parameter meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List the public status updates posted on suggestions') and even enumerates the returned fields (message, supporters emailed, opens/clicks, reactions), so the agent knows what this returns. It stops short of distinguishing itself from the similarly named sibling uservoice_list_statuses, which lists statuses rather than status updates.

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, no exclusions, and no pointer to alternatives such as uservoice_list_statuses or uservoice_post_status_update. The GET path implies a read/listing operation, but the agent must infer the use case entirely.

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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds real value by disclosing the shape of the return payload (which fields come back) in the absence of an output schema, plus the underlying GET admin endpoint — non-trivial context beyond the annotations. It does not mention pagination mechanics or rate limits.

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

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

Three tight sentences: purpose and payload first, filters second, endpoint last. Almost no waste; the endpoint mention is the only arguably redundant element and it is short.

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 16-param read tool with no output schema, the description supplies exactly the missing piece — the returned field set — while the schema carries all parameter semantics and annotations carry the safety profile. An agent has enough to select and invoke 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?

With 16 parameters at 100% schema description coverage, the schema already documents paging, sort syntax, cursor preference, and every filter. The description only restates the filter categories generically and adds no format or constraint detail beyond the schema (e.g., nothing about cursor vs page interaction or sort syntax). Baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb (list or search) and resource (suggestions/ideas), and enumerates the returned fields (title, body, state, vote/supporter counts, revenue, links). This distinguishes it implicitly from get_suggestion (single record) and create_suggestion (write), though it never names a sibling explicitly.

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

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

The filter enumeration (text, forum, category, status, state, label, time) implies how the tool is meant to be driven, but there is no explicit when-to-use versus get_suggestion/uservoice_list_feedback_records, and no stated exclusions or prerequisites. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds the endpoint 'GET /api/v2/admin/supporters', which usefully signals an admin-scoped read. It does not describe pagination or cursor behavior, though the schema covers those parameters.

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

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

Two compact sentences with the resource statement front-loaded and the filter/endpoint details following. Every clause carries information, though the field enumeration ('who supports what, how, importance, subscription') is slightly listy rather than tightly integrated.

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 sketches the shape of a supporter record (user, suggestion, channel, importance, subscription), and the admin endpoint hint covers auth context. All 9 optional params are fully documented in the schema and safety is handled by annotations, leaving little an agent needs that 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 every one of the 9 parameters is already documented with type, bounds and pattern. The description's 'filter by suggestion, user or forum' merely frames those filters conceptually and adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

Clear verb ('List') plus a specific resource ('supporters (voters) of suggestions'), and it enumerates the record fields (who/what, channel, importance, subscription). It distinguishes itself from list_suggestions by describing voter records rather than the suggestions themselves, though it doesn't explicitly name a sibling to route against.

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, nor any exclusions. 'Filter by suggestion, user or forum' describes capability, not usage context, so the agent must infer the calling conditions from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results include satisfaction score and supported suggestion count, but says nothing about pagination behavior, result limits, or auth requirements for the /api/v2/admin/users endpoint.

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

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

Two compact sentences that front-load the action and then enumerate filters, ending with the endpoint. Efficient, though the parenthetical field list is parenthetical clutter rather than essential 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 an 8-parameter read tool with no output schema, the description covers the purpose and filter dimensions but omits pagination behavior (cursor vs page interplay is only in the schema), auth requirements, and response shape. Adequate but leaves gaps an agent must infer from the schema alone.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema with format and semantics. The description only restates the query/email/suggestion filter concepts at a high level and adds no syntax or behavior beyond the schema. Baseline 3 applies.

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

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

States a clear verb (list/search) and resource (end users and admins), and enumerates returned fields plus filter dimensions. It distinguishes itself reasonably from uservoice_get_user (single lookup) but doesn't explicitly name list_supporters or other list siblings as alternatives, so it stops short of a 5.

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

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

The description implies usage through the filter options it enumerates (text, email, supported suggestion), which tells an agent what dimensions are queryable. However, it gives no explicit when-to-use vs. when-not, no guidance on choosing this over uservoice_get_user or uservoice_list_supporters, and no 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?

Adds value beyond annotations by specifying that updates are public, that supporters are emailed ONLY when notify_supporters is true, and giving the admin endpoint. The annotation destructiveHint=true is not explained (what gets destroyed), leaving a small 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?

Front-loaded with the WRITE marker, then purpose, key conditional, and endpoint in a tight single line with zero waste.

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

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

Complete enough for a mutation tool: purpose, safety-relevant conditional (supporters notified), and endpoint are covered. Without an output schema the description could say more about the response, but the essentials are present.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds only the conditional behavior of notify_supporters and references uservoice_list_statuses for status_id, minor value over the schema baseline.

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

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

States a specific verb+resource: posting a public status update on a suggestion, with the optional status change. Clearly distinct from siblings like uservoice_add_comment or uservoice_add_note by naming the status-update resource and the POST endpoint.

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

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

Names uservoice_list_statuses as the lookup for valid status IDs and explains the notify_supporters condition, giving clear context. No explicit when-not-to-use guidance, but the routing to a sibling tool is present.

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