Device Magic MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description reinforces idempotency concretely ('no effect') and discloses the state transition and downstream consequence (device can receive forms). It stops short of noting permissions or what the response contains, but on top of annotations this is solid.

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, leading with a 'WRITE:' marker and the core action, then the edge case, then the endpoint. Nothing is wasted.

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

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

For a single-parameter mutation with full annotation coverage, the definition supplies precondition, effect and idempotency. Only the return payload is unspecified, a minor gap given there is no output schema.

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

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

Only one parameter, documented in the schema at 100% coverage including a cross-reference to list_devices' `id` field. The description adds nothing beyond the schema, which is the baseline expectation here.

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

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

States a specific verb ('approves') and resource ('a device'), plus the exact precondition (pending_approval is true) and the outcome ('so it can receive forms'). This is unambiguously distinct from read siblings like get_device and list_devices.

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?

Makes the trigger condition explicit ('a device that is waiting for approval') and covers the degenerate case ('approving an approved device has no effect'). It doesn't name an alternative tool for devices not in pending state, but the condition is clear enough to route correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely non-obvious traits beyond that — no content is downloaded and the response shape for spreadsheets differs (tables and columns only present for that type). The raw endpoint path adds minor operational context.

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

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

Two short sentences with zero padding; the most decision-relevant fact (metadata only, no file content) is front-loaded and the conditional spreadsheet behavior is tucked in efficiently.

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

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

There is no output schema, so the description carries the return-value burden and does so reasonably: it enumerates status, version, and conditional tables/columns. It stops short of describing the object shape or error behavior for an invalid id, keeping it just shy of fully complete.

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

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

Schema coverage is 100% and the single parameter is documented in-schema (including how to obtain it from list_resources), so the schema does the heavy lifting. The description only hints at the id via the path template and adds no format or constraint detail beyond it — the baseline 3 is appropriate for a one-parameter tool.

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

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

The description names the specific resource (one resource) and enumerates the returned metadata fields (status, version, tables/columns), which separates it from devicemagic_list_resources. It is a noun phrase rather than a verb phrase, but the operation (describe/fetch metadata for a single resource) is unmistakable.

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 file content itself is not downloaded' implies the intended use case (inspect a resource without pulling bytes) and acts as an implicit when-not. However, it never states when to prefer this over list_resources or how the agent should follow up if it needs the actual content, leaving the routing to the agent to infer.

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 meaningful behavioral context by stating that credentials and tokens are never returned, which is important for an agent to know before calling.

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

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

Three short sentences with zero waste: the resource, the security constraint, and the REST endpoint are all front-loaded. Every sentence earns its place.

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

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

For a simple read-only retrieval tool with full schema coverage and rich annotations, the description is nearly complete. It adds a useful security note and the endpoint path, though it does not describe what fields are actually returned.

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 destination_id are already documented in the schema. The description reinforces the endpoint path but adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states the resource precisely ('One destination of a form') and implies single-item retrieval, which distinguishes it from list_destinations. However, it never explicitly contrasts with that sibling or states a retrieval verb beyond the title.

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

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

Usage is only implied: an agent can infer this is for fetching one destination when the id is known. There is no explicit guidance on when to use this versus list_destinations or get_form, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds the concrete REST path (GET /organizations/{org}/devices/{id}.json), confirming a plain read, but says nothing about 404 behavior, permissions, or org scoping constraints.

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; the field list comes first and the endpoint second. The opening 'One device:' is a fragment, but it is front-loaded and readable rather than 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?

For a one-parameter read with no output schema, the enumerated return fields partially substitute for a return spec, which is genuinely useful. Still missing are failure cases (invalid/unknown id) and any hint about org resolution implied by the {org} placeholder in the path.

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 device_id is already documented as the numeric `id` from list_devices, so the description adds nothing about the parameter. Baseline 3 applies because the schema carries the full burden.

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 (a single device) and enumerates exactly which fields come back, which lets an agent distinguish it from list_devices. The verb 'get' is only implied by the title rather than the description text, but the intent is unmistakable.

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 'One device' versus the sibling devicemagic_list_devices, plus the explicit endpoint path showing a single-id lookup. It never says when to prefer this over listing or over devicemagic_describe_resource, and gives no guidance on what to do if the id is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying REST path and the include_inputs=true flag, which hints that prefilled input values are returned but doesn't explain the response or any failure modes (e.g. unknown dispatch 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?

Two short, front-loaded sentences with no filler. The raw endpoint string is borderline redundant with an MCP tool but does at least convey the include_inputs flag.

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

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

For a two-parameter read with full schema coverage and read-only annotations, the definition is minimally adequate. Without an output schema, though, the phrase 'the values it was prefilled with' leaves the return shape vague, so an agent cannot anticipate the response structure.

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

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

Schema description coverage is 100% and both parameters carry their own descriptions with examples, so the schema does the heavy lifting. The description contributes nothing additional about dispatch_id or device_identifier beyond what the schema states.

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 and scope: a single dispatch of a device, including prefilled values. The singular 'one dispatch' implicitly contrasts with the list_device_dispatches sibling, though it never names that sibling explicitly.

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

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

Usage is only implied by the phrasing 'one dispatch ... of a device' – an agent can infer this is the detail fetch for a single dispatch after listing. There is no explicit when-to-use, no prerequisite note (e.g. needing id and identifier from a prior list call), and no alternative named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that — it discloses what the payload contains (title, questions/pages, identifier types) and names the underlying endpoint GET /organizations/{org}/forms/{id}.json — but says nothing about failure modes or behavior when the form or version does not exist.

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, front-loaded with the resource definition and closing with the endpoint. Every clause carries information; the fragmentary style is dense rather than padded, though the trailing URL is the least essential element for an agent that cannot call it directly.

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

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

With no output schema, the description must describe the return value, and it does so at a useful level of abstraction: title, questions/pages, identifiers and their types, plus the key insight that those identifiers are the keys used in submissions and dispatch payloads. That is enough to call the tool correctly and to use its result downstream, though deeper shape detail is absent.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the default-latest behavior of version and the pointer to list_forms for form_id. The description's 'Optionally a specific version' restates the optionality already encoded in the schema rather than adding format or constraint detail, so the baseline of 3 applies.

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

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

States a specific resource and scope: a single form's definition, including its title, pages/questions, and the identifiers and their types. The 'One form's definition' framing contrasts cleanly with the list_forms sibling without needing to name it, and the parenthetical explaining that identifiers are the keys inside submissions and dispatch payloads pins down the meaning of the returned content.

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 (fetch a form, optionally at a specific version) but never states when to prefer this over devicemagic_list_forms or the other get_* siblings. There are no exclusions, prerequisites, or error conditions mentioned, so the agent must infer the routing decision 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, openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that: the exact API path and, importantly, the fields each destination record exposes — which matters since there is no output schema. It does not mention pagination or ordering, a minor 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?

One tight sentence leading with what is returned and the per-form scope, with the endpoint appended as a compact reference. 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 single-parameter read tool with full annotation coverage and no output schema, listing the returned fields makes the definition largely self-sufficient. Only ordering/pagination behavior is left 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% and the sole parameter form_id is already documented with its source (`id` of list_forms). The description adds no further syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (list) with a precisely scoped resource (one form's submission destinations) and enumerates what the records contain: id, active flag, format, transport types, timestamps. An agent can distinguish this from get_destination or list_dispatch_recipients by the plural/collection framing, 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: the phrase 'one form's submissions' signals it requires a form context and returns the full collection, versus get_destination's single item. No explicit when-to-use, prerequisites, or alternative are called out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that only 'outstanding' dispatches are returned and pins the REST endpoint, which is useful context beyond the annotations. It does not define what 'outstanding' means, nor whether results are paginated or limited in count.

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 no filler; the scope qualifier is front-loaded. The endpoint reference is mildly redundant with the tool name but cheap and sometimes useful for API-aware agents. 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?

This is a simple one-parameter read with annotations and no output schema, so description requirements are modest. Still, with no output schema the description should say roughly what a dispatch entry looks like or how many come back, and 'outstanding' remains undefined. Adequate but with clear gaps.

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

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

Schema coverage is 100% and the single device_identifier parameter is fully documented in the schema with format guidance. The description's endpoint path ({identifier}) mirrors but does not extend that meaning. Baseline 3 applies when the schema carries the parameter burden.

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 its scope precisely: outstanding dispatches belonging to one device. An agent can tell that it returns a filtered collection rather than all dispatches. It stops short of naming sibling alternatives such as devicemagic_list_dispatches or devicemagic_get_dispatch, and the verb is only carried by the tool name rather than the description text.

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

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

There is no explicit guidance on when to use this versus devicemagic_list_dispatches (all dispatches) or devicemagic_get_dispatch (single dispatch). The word 'outstanding' hints at a pending-only filter but never defines it or states prerequisites. An agent must infer selection 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 safety is covered. The description adds real context beyond them by enumerating the returned fields, including the 'approval is pending' flag, which is a behavioral detail an agent would otherwise have to discover at runtime. Pagination or result-size behavior is not mentioned, which is the main remaining gap.

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

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

One dense sentence that front-loads the resource and then the payload fields, with the endpoint appended as a compact technical anchor. It is efficiently sized, though the raw path adds little for an agent that cannot pass path parameters.

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 enumeration of returned fields is what makes this definition usable, and it does that job. It stops short of describing pagination, ordering, or whether the list can be large under openWorldHint, which is the notable omission.

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

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

Zero parameters, so the baseline is 4. The description's reference to the organization's devices and the path template GET /organizations/{org}/devices.json makes clear that the org scope comes from context/auth rather than an argument, which is a useful clarification.

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 (the organization's devices), and enumerates the entity types covered (phones, tablets, web-form users) plus the fields returned. It is clearly distinguishable from devicemagic_get_device, though it never names that sibling explicitly.

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

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

Usage is only implied: the verb 'List' plus the field enumeration suggests scanning the inventory, and the existence of get_device for single-item fetches is left for the agent to infer. No when-to-use or when-not guidance 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 adds genuinely new context: the Enterprise-plan prerequisite and the semantic that only incomplete dispatches appear. It stops short of noting pagination or result-size behavior for an org-wide listing.

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

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

One front-loaded sentence carries the resource, its definition, scope, and returned fields, followed by two short sentences for the plan gate and endpoint. Dense but tight; the raw 'GET /api/v2/...' path is marginal value for an agent but small.

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

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

With no output schema, the description compensates by enumerating the returned fields (id, form name/namespace, device, scheduled time), and it discloses the plan requirement. It leaves unclear whether results are paginated or capped for a full-organization listing, which matters for a no-filter 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?

Zero parameters, so the 4 baseline applies; the description correctly signals that there are no filters by emphasizing 'whole organization'. The parenthetical and field enumeration describe what comes back rather than adding parameter meaning, but nothing is missing on the input side.

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 outstanding dispatches') with an inline definition of what a dispatch is (prefilled forms pushed to devices, not yet completed) and an explicit org-wide scope. The 'whole organization' qualifier plus the per-dispatch field list cleanly separates it from the device-scoped sibling devicemagic_list_device_dispatches.

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 org-wide vs. device-level distinction is implied by the scope phrase, and the Enterprise-plan gate is stated, which is real selection guidance. But no sibling is named and there is no explicit when-not (e.g. use list_device_dispatches when you only want one device's dispatches), so routing 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, openWorldHint=true, and destructiveHint=false, so safety behavior is covered. The description adds the default result count and pagination behavior, but does not add other behavioral context such as return shape, auth needs, 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?

The description is a single compact sentence that front-loads the resource and includes pagination guidance without unnecessary detail. The endpoint reference is brief and does not distract from the main purpose.

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

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

For a simple read-only list tool with full parameter descriptions and safety annotations, the description is nearly complete: it states what is listed, the default page size, and how to paginate. Return-field details are absent, but no output schema exists and the recipient concept is adequately conveyed.

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 and items are already documented in the input schema. The description mentions items and page for retrieving more results, but adds no syntax or meaning beyond what the schema provides; 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 identifies the resource clearly: devices and web-form users to which a dispatch can be sent. It also names the backing endpoint, but it does not explicitly distinguish this combined recipient list from sibling list tools such as devicemagic_list_devices or devicemagic_list_forms.

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 'a dispatch can be sent to' implies this tool is used before send_dispatch, but no explicit when/when-not guidance or alternatives are provided. The pagination note is useful, though it is parameter-level guidance rather than tool-selection 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, destructiveHint=false and openWorldHint=true, so the description's added value is the payload shape: it names the five returned attributes and explains that 'namespace' is the form's unique id used for dispatching. That is real behavioral context beyond the structured fields, though ordering and pagination behavior remain unstated.

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 tightly packed sentence with the purpose front-loaded and the field list immediately after. The trailing 'GET /organizations/{org}/forms.json' is marginally redundant for an agent but does confirm scope is the whole organization rather than a sub-resource.

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 enumeration of returned fields and the clarification of 'namespace' adequately tells the agent what it will get back. Only the absence of any result-size or ordering expectation keeps it from being 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 is 4; there is no parameter semantics to document. The description instead describes the response fields, which is a reasonable substitution.

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 organization's forms') plus the fields returned, so the operation is unambiguous. It does not distinguish itself from the sibling devicemagic_get_form (single-form retrieval), leaving the list-vs-get distinction implicit.

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 instead of devicemagic_get_form or devicemagic_list_submissions, and no prerequisites or scoping notes are given. Usage is only inferable from the word 'List'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered structurally. The description adds the underlying REST endpoint, which is mild context but not behavioral disclosure — it says nothing about how pagination behaves (page size, total counts) despite exposing a page parameter, nor about result caps or ordering.

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

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

Two sentences, zero filler, with the core definition front-loaded and the practical narrowing options second. The parenthetical gloss is compact and high-value rather than redundant.

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

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

For a read-only list tool with complete schema documentation, full annotation coverage and no output schema, the description covers what the tool is and how to narrow it. The one substantive gap is pagination semantics — a page parameter exists but neither description nor schema says how large a page is or how to know when to stop — so it is strong but not airtight.

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 explains that 'filter' matches part of the name and 'tags' matches any supplied tag, so the description's 'optionally narrowed by a name filter or by tags' adds no meaning beyond it. This is the baseline-3 case where the schema carries parameter documentation.

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

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

A specific verb+resource ('List the organization's groups') with a genuinely useful gloss — 'which devices see which forms' — that explains what a group represents in the domain, something neither the name nor title conveys. It stops short of explicitly distinguishing itself from sibling list tools like devicemagic_list_devices or devicemagic_list_forms, but the resource concept does the disambiguating implicitly.

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 says the result can be 'optionally narrowed by a name filter or by tags', which implies when to supply those parameters, but it never states when this tool should be chosen over a sibling, nor any 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, and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by naming the concrete endpoint and enumerating the returned fields (id, original filename, version, description), which serves as return-value context since there is no output schema.

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

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

A single compact sentence with the resource scope, a parenthetical definition, the returned fields, and the endpoint, all front-loaded with zero filler. Every clause earns its place.

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

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

For a zero-parameter read tool with no output schema, the description supplies the scope, the return fields, and the endpoint, which is sufficient to call it correctly. It could have added whether results are paginated or how many resources are typically returned, but nothing critical 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?

The tool takes zero parameters, so there is nothing for the description to document; baseline credit applies. The description correctly presents this as an unfiltered organization-wide list, matching the empty schema.

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

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

States a specific verb and resource and disambiguates the vague term 'resources' by defining them as lookup tables and files used by forms, then previews returned fields. It does not, however, distinguish itself from the sibling devicemagic_describe_resource, which an agent could easily confuse with this one.

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: listing plus the described fields suggests 'enumerate to get ids, then call describe_resource for detail', but the description never says when to use this instead of describe_resource or any other list tool. No exclusions or preconditions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the return shape (form info, device/user/timestamp/submission_id metadata, answers), the pagination envelope (current_page, total_pages, total_count), and the active-destination prerequisite.

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 compact and front-loads the core definition (submitted data of one form) before metadata, return shape, filters and endpoint. The date format 'yyyy-mm-dd' is duplicated in the schema and the endpoint path is of marginal value to an agent, keeping it short of a 5.

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

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

There is no output schema, and the description compensates by describing both the record structure and the paging envelope. Combined with the precondition and endpoint, an agent has what it needs to page through results correctly, with only error behavior for an inactive destination left implicit.

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 are already documented in the schema, including the yyyy-mm-dd patterns and the 1-100 per_page bounds. The description restates the date format and hints at paging via total_pages but adds no new semantics beyond the structured fields, so the baseline 3 applies.

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

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

The description names a specific resource and scope: submitted records for ONE form, with a clear note that data comes from the form's Device Magic Database destination. This clearly separates it from devicemagic_list_forms and devicemagic_get_form, though it never names 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?

It states a real precondition for use — the Device Magic Database destination must be active on the form — plus the optional from_date/to_date filtering behavior. No alternative tool is named, but among the listed siblings there is no competing submissions-listing tool, so the gap is minor.

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

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

Annotations already flag destructiveHint=true, so the description earns credit for adding the real consequences: the form disappears from the device, the action cannot be undone, but it is re-creatable by resending. That nuance (irreversible yet recoverable) is not in the annotations. It doesn't say what happens on an already-revoked or unknown dispatch id, which keeps it at 4.

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 mutation type and the core action, closing with the endpoint. Every clause carries information the agent needs (effect, reversibility, recovery path, route) with zero filler.

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

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

For a destructive 3-param write with no output schema, the description covers effect, irreversibility, recovery, and endpoint. Remaining gaps are edge cases such as behavior on missing or already-sent dispatches and whether any success payload is returned.

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 explains all three parameters, including that dispatch_id comes from list_device_dispatches and that confirm must be true. The description adds no parameter-level 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?

Specific verb + resource ('withdraws one outstanding dispatch from a device'), plus the observable consequence ('the form disappears from the device') and the exact endpoint. An agent can distinguish it from devicemagic_send_dispatch and devicemagic_get_dispatch without opening any schema.

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

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

The leading 'WRITE:' tag plus 'outstanding dispatch' scopes when the tool applies, and 'the dispatch can be sent again' implicitly routes an agent to re-issuing via send_dispatch. No explicit when-not or named alternative is stated, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description earns credit for adding context the annotations don't: the Enterprise plan requirement, that the device's user will see the form, and that duplicate calls create two dispatches. It could say more about reversibility (i.e., pairing with revoke_dispatch) or failure modes, but the plan/auth and duplication details are genuine additive value.

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

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

Front-loaded with the WRITE marker and the core effect, and every clause carries information (idempotency, plan, payload shape, endpoint). It is a single dense block, however; splitting the payload rule into its own sentence would improve 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 mutation with no output schema, it covers the effect, preconditions, idempotency, and payload construction. It stops short of telling the agent how to retrieve or undo the resulting dispatch (get_dispatch / revoke_dispatch), which would close the remaining loop.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining how `payload` keys map to question identifiers from get_form and how nested subforms and repeat groups are represented. That is real semantic guidance beyond the schema's 'Prefilled values keyed by question identifier.'

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

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

Opens with an explicit verb-and-resource statement ('pushes a form ... to one device') plus an analogy ('like assigning a job') that pins down the effect. Distinguishes it from the read-side siblings (list_dispatches, get_dispatch, revoke_dispatch) and names the sourcing siblings list_forms and get_form.

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 preconditions (Enterprise plan, confirm gate, device already exists) and a warning against duplicate calls, which effectively tells the agent when not to re-invoke. It does not explicitly contrast with siblings like revoke_dispatch or list_device_dispatches, so routing guidance is implied rather than spelled out.

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