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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the 'must be retired' precondition and says nothing about what reactivation actually does (re-enabling management, signaling a device, behavior on a non-retired device) or what failure modes look like.

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 verb and free of padding. It is efficient to the point of being thin, but nothing in it is wasted or buried.

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

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

For a one-parameter mutation with rich annotations and no output schema, the definition is adequate but sparse: an agent knows what it does and the precondition, yet not the observable effect or what happens when the precondition is unmet.

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 single parameter's description even points at list_devices as the source of the ID. The tool description adds nothing about the parameter, 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 verb ('Reactivate') and resource ('a device') plus a meaningful scope qualifier ('previously retired in Miradore'), which distinguishes it from generic siblings like update_device. It does not, however, name or contrast itself with any sibling explicitly, so the reader must infer the boundary.

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

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

The phrase 'previously retired' implies the precondition for use, but there is no explicit when-to-use / when-not-to-use guidance and no routing to alternatives (e.g. use update_device for other device changes, or list_suspended_devices to find candidates).

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add context. It usefully discloses the non-obvious side effect that tags can trigger business policies that install apps and profiles. It stops short of stating whether the tag must already exist or what permissions are required.

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

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

Two short sentences with the operation front-loaded and no padding; the second sentence earns its place by explaining the tag's effect. Nothing is redundant, though the description is minimal for a mutation tool.

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

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

For a two-parameter mutation with full schema coverage and annotations declaring idempotency and non-destructiveness, the description supplies purpose and the key downstream side effect. The remaining gap is the preconditions for the tag's existence and required permissions, which is minor given the annotation coverage.

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

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

Schema description coverage is 100%, so both parameters (tag and device_id) are already documented in the schema, including the device_id provenance hint pointing at list_devices. The description adds no further meaning about parameter values or formats, 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 ('Add a tag to a device') and the second sentence explains what a tag is and does. The operation is clearly distinct from remove_device_tag, add_user_tags, and list_tags in the sibling list, though the description itself does not 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?

Implies when the tool is relevant by noting tags group devices and can trigger policies that install apps and profiles, which hints at the consequence of using it. However, it gives no explicit when-to-use vs when-not guidance and never points to alternatives such as add_user_tags or remove_device_tag.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say whether tags are appended to existing tags or replace them, whether unknown tags are auto-created, or whether the open-world behavior means new tags can be introduced. Those are exactly the behavioral questions an agent has for a tag-assignment mutation.

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

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

A single front-loaded sentence with zero redundancy and no filler. Its brevity is a virtue structurally, though it borders on under-specification rather than over-wordiness.

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

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

The tool is simple (2 required params, no nesting, no output schema) and the annotations cover idempotency and safety, so the bar is low. Still, the append-vs-replace question and the tag existence prerequisite are unresolved, which matters for a mutation the agent may call repeatedly.

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 50% (only email is described in-schema). The description's 'one or more tags' conveys the minItems=1 constraint on the undocumented tags array, which is modest added value, but it says nothing about tag format, case sensitivity, or maximum count. Baseline 3 is right given partial schema coverage.

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 ('Assign') and resource ('one or more tags to a user'), which is enough to distinguish it from remove_user_tag and from the device-oriented add_device_tag sibling. It stops short of naming those alternatives explicitly, so it is clear but not fully differentiated.

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

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

There is no when-to-use guidance, no prerequisite (e.g. whether the tag must already exist, whether the user must exist), and no reference to the sibling tools that undo or parallel this one. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorld=true, so the safety profile is covered. The description usefully explains the deferred effect (linking happens at enrollment, not now), but it does not say what happens when an identifier is already bound to another user, nor whether pre-assignments expire or can be overwritten.

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, no filler: the mechanism and outcome come first, the operational timing rule second. Nothing is repeated and nothing is buried.

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

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

For a two-parameter tool with full schema coverage, rich annotations, and no output schema, the description covers purpose, effect, and timing adequately. The only real gap is conflict/duplicate handling, which matters for an idempotent pre-assignment operation but is a modest omission.

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

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

Schema coverage is 100% and both parameters are documented, so the baseline is 3. The description adds only a light gloss on identifiers ('serial numbers, IMEIs, etc.'), which largely duplicates the schema's own wording; the 100-item cap and email semantics are left to the schema.

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

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

States a specific verb ('Pre-assign') and resource ('device identifiers') plus the downstream effect: devices are linked to the user automatically upon enrollment. That effect clause distinguishes it well from the read-side sibling get_user_device_identifiers and the inverse remove_device_identifier_from_user, though neither 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?

Gives a concrete timing rule: 'Use this before powering on a new device,' which tells the agent the precondition for calling it. It stops short of exclusions, e.g. what to do if the identifier is already assigned or whether to prefer this over updating an existing enrollment.

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, openWorldHint=true and destructiveHint=false, so the mutation/safety profile is covered. The description adds nothing beyond that: it does not say whether duplicate emails are rejected, whether the call is idempotent, whether an invitation/email is sent, or what permissions are needed for a tenant-wide write.

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

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

A single front-loaded sentence with no filler; the resource and its purpose lead the sentence. It is efficient, though efficiency here partly reflects under-specification rather than tight writing.

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

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

For a 5-parameter mutation tool with 20% schema coverage and no output schema, the description is too thin: it omits duplicate-handling behavior, permission requirements, and what the caller receives back (e.g., a user id needed for later assignment calls). Only the bare purpose is 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 only 20% – just 'email' is documented, while first_name, last_name, middle_name and phone_number carry no schema descriptions. The description does not compensate at all: it never mentions required identity fields, format expectations, or whether middle_name/phone_number are optional.

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 a specific resource ('a Miradore user') with an added rationale ('that devices can be assigned to'), which distinguishes it from sibling tools like update_user, list_users and assign_device_identifiers_to_user. It stops short of naming an alternative explicitly, so it is clear but not maximally differentiated.

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

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

There is no guidance on when to call this versus update_user (i.e., whether the user already exists), no prerequisites, and no mention of what happens if the email is already registered. The agent must infer the entire create-vs-update decision.

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

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

Annotations already declare this is a non-read-only, open-world, non-destructive mutation, so the safety profile is covered. The description usefully adds the lookup dependency on get_application, but says nothing about whether redeployment replaces an existing install, whether the call is synchronous, or what happens on failure.

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, action first and prerequisite second, with no filler. Every clause carries operational 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 three-parameter mutation with full schema coverage, no output schema, and annotations covering the safety profile, the description supplies what the structured fields cannot: the prerequisite lookup chain. The main remaining gap is the absence of any statement about deployment outcome or reversibility.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond it by explaining that deployment_method_id must be sourced from get_application, resolving the schema's near-circular gloss 'The application's deployment method ID.' It says nothing extra about the optional managed_configuration_id.

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 (Deploy) and resource (an application to a device) and immediately bounds the mechanism to the app's deployment methods, which separates it from deploy_config_profile and the other sibling tools. An agent can identify the operation without opening the schema.

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

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

Gives an explicit prerequisite workflow: call get_application first to obtain the deployment method ID. It lacks any when-not guidance (e.g., what to do if the app is already deployed on the device, or when to prefer deploy_config_profile), but the positive usage path is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavior beyond that: nothing about idempotency (does redeploying overwrite an existing profile assignment?), what changes on the device, required permissions, or failure modes. For a write operation that alters device state, that is a real gap even with the lower annotation-based bar.

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

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

One short sentence, front-loaded with the action and resource, with the provenance hint in parentheses where it belongs. 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 two-parameter mutation with no output schema, the definition is minimally sufficient: an agent knows what to call and what IDs to supply. It is not complete enough to predict the outcome — no statement of what a successful deployment does to the device, whether it replaces a prior profile, or how errors surface.

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 device_id and profile_id are already documented in the schema, including the 'from list_devices' provenance. The description's '(from list_config_profiles)' is the only added meaning and it mirrors the schema pattern rather than extending it; baseline 3 applies.

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

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

The description states a specific verb ('Deploy') plus resource ('configuration profile') and target ('to a device'), so the operation is unambiguous. It also points at the source of the profile via list_config_profiles, which helps separate it from read-only siblings, though it never mentions the closely related deploy_application sibling.

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

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

It gives one useful routing hint — get the profile_id from list_config_profiles — which implies 'call that first.' There is no when-not guidance, no prerequisites (e.g., device must be enrolled/active), and no mention of when to prefer deploy_application or remove_config_profile.

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 read-only, non-destructive, open-world, so the description rightly focuses on content: it spells out the four attention criteria (stale check-in, no assigned user, passcode not set, encryption not enabled), which an agent could not infer otherwise. It stops short of saying whether the summary is cached, how expensive it is, or how the sections are shaped.

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

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

One compact, front-loaded passage with no filler; the semicolon-separated clauses map to the summary's sections. Slightly dense as a single sentence, but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing return content, and it does so thoroughly: the three count breakdowns, OS versions, and the per-category attention lists. Both parameters and the safe read-only nature are covered, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description reinforces stale_days by restating the attention rule and implicitly ties 'lists of devices needing attention' to the max_listed cap, but adds no format or interaction detail beyond the schema.

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

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

States a specific verb and resource ('Summarise the whole fleet in one call') and then enumerates exactly what is produced: counts by platform/online/lifecycle status, OS versions in use, and attention lists. This clearly separates it from list_devices or get_device, which return individual records.

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 usage context ('Good for a daily check-in or "is anything wrong?"'), which implies when to reach for it, but never names alternatives or exclusions. It does not tell the agent to prefer list_devices when it needs full device objects or pagination.

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 structurally. The description adds genuinely new behavioral context: the response includes deployment methods, and the ID is discoverable from the console URL on the application page. It does not say what happens on an unknown ID, but the additions materially exceed the annotation set.

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

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

Two sentences, no filler, and the core scope is front-loaded ahead of the discoverability hint. Every clause 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?

For a single-required-parameter read tool with no output schema, the description covers what is fetched, why it matters, and how to source the ID. The only gap is return-shape detail—what 'deployment methods' look like and whether the object includes other fields—which is minor given the tool's simplicity.

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

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

Schema coverage is 100%, so the baseline is 3 for the single 'id' parameter. The description earns above baseline by explaining where an agent can obtain a valid ID (the Miradore console URL on the application's page), which the schema's terse "Miradore application ID." does not convey.

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 ("Get an application from the Miradore application catalog by its ID") plus the returned payload (deployment methods). It is clearly distinguishable from list_config_profiles, deploy_application, and the other device/user siblings because it names the catalog and the lookup key.

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 "(needed for deploy_application)" gives an explicit downstream-use condition, which is strong when-to-use guidance. It stops short of when-not guidance (e.g., use a catalog list tool to find IDs you don't already have), so it is clear context without full routing.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that detail sections are optional/cherry-pickable, which hints at response-shape control, but it does not say what the base payload contains when 'include' is empty, nor any cost, size or latency implications of requesting many sections.

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 with zero filler: purpose first, then the section catalog. The parenthetical glosses make it long-ish, but each clause carries information an agent cannot get from the bare enum.

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 2-parameter read-only fetch with full schema coverage and no output schema, the description covers what it returns, how to scope the response, and where the ID comes from. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description goes further by glossing each enum value the schema leaves bare ('os_updates (pending Apple updates)', 'management (client/enrollment info)', 'installed_profiles (profiles on an Apple device)'). That per-section meaning is real value beyond raw enum strings, and only the 'id' format is left to the schema.

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

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

States a specific verb and resource: 'Get one device by its Miradore device ID', which is clearly a single-record fetch. Singular 'one device' implicitly distinguishes it from the sibling list_devices, though the sibling is never 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: 'by its Miradore device ID' plus the schema note '(from list_devices)' suggests the discovery-then-fetch flow, but the description never states when to call this versus list_devices or device_health_summary. No exclusions or prerequisites 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 genuine behavioral context the annotations do not: the result is gated on location tracking being enabled for the device. It omits what happens when tracking is off (empty result vs. error) and whether the response is paginated or time-bounded.

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

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

Two short sentences with the resource and the enabling precondition front-loaded, and no filler. It is efficient, though the parenthetical is slightly buried for a condition that determines whether the tool returns anything at all.

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 four-parameter read-only tool with no output schema and a fully documented schema, the description covers purpose and the key precondition. The notable gap is what happens when start_date/end_date are omitted — whether there is a default window or the full history is returned — which directly affects how an agent should call it.

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

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

Schema description coverage is 100% and every parameter carries an example-bearing description, so the baseline is 3. The description only restates that dates are optional, adding no meaning beyond the schema about start_date/end_date pairing or time_zone defaults.

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: 'Get reported locations for a device'. The 'reported' qualifier signals these are stored/reported positions rather than live tracking. It is distinguishable from the sibling get_device, though the description never names siblings to anchor that distinction.

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

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

Adds one real precondition ('only if location tracking is enabled for it') and notes dates are optional, which implies the call works without a range. There is no explicit when-to-use versus alternatives (e.g. get_device or device_health_summary) and no guidance on choosing a range.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about the purpose of these identifiers (they auto-link devices at enrollment), but says nothing about what is returned when the user has no pre-assigned identifiers or how unknown emails are handled.

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 operation and resource, with the enrollment rationale placed after as supporting context. There is 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?

This is a simple one-parameter read tool with full schema coverage, annotations, and no output schema, so the description covers nearly everything an agent needs. The only real gap is edge-case behavior, such as an empty result set or an unknown email.

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

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

Schema coverage is 100%, with the single email parameter documented as 'User email.', so the baseline is 3. The description slightly reinforces the parameter's meaning by tying the lookup to 'a user' whose devices get linked, adding a bit of domain context beyond the schema, so a modest bump is warranted.

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

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

The description gives a specific verb and resource ('List device identifiers ... pre-assigned to a user') and even names example identifier types (serial numbers, IMEIs). It implicitly separates itself from assign_device_identifiers_to_user and remove_device_identifier_from_user by framing the data as already pre-assigned, 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?

Usage is only implied by the stated purpose and the enrollment-linking rationale; there is no explicit 'use this when' statement, no mention of an alternative tool such as get_device or list_devices, and no prerequisite (e.g., the user must already exist) spelled out. An agent can infer the intent but gets no routing 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 safety profile is covered. The description adds that results carry IDs usable by deploy_config_profile, which is genuine value, but it does not disclose anything about include_deleted behavior or result volume/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?

A single sentence with the resource and its purpose front-loaded, a compact parenthetical for examples, and no redundant restatement of the title or annotations.

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

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

For a simple two-parameter read-only list tool with no output schema, the description covers what is returned (profiles plus IDs) and why. The remaining gap is the undocumented include_deleted flag, which is a minor but real omission.

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

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

Schema coverage is only 50%: the 'os' enum is documented in the schema, but 'include_deleted' has no description anywhere. The description does not compensate — nothing explains that deleted profiles can be included or what the default excludes, leaving one of two parameters semantically opaque.

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 configuration profiles defined in Miradore') and enumerates profile categories (Wi-Fi, restrictions, email). It also names the downstream sibling 'deploy_config_profile', so an agent can tell this apart from list_devices, list_tags, or deploy_config_profile itself 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?

The phrase 'for use with deploy_config_profile' gives a clear use context: fetch IDs before deploying a profile. There is no explicit when-not guidance (e.g., not needed if you already know the profile ID), but the intended role is unambiguous.

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 disclosing what is returned (IDs and names) and its discovery role for a write tool, but says nothing about pagination, result size, or whether the list is tenant-wide.

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 named first, the returned fields in parentheses, and the downstream consumer at the end. Every clause carries information and 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 zero-parameter read tool with no output schema, the description supplies the essentials: what it lists, what fields come back, and where the result is consumed. Missing only minor operational details such as whether the listing is paginated or scoped to the caller's site.

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. The description's parenthetical about IDs and names describes output rather than inputs, and no parameter meaning is needed or missing.

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 custom attributes configured in Miradore') and even names the return content (IDs and names). The reference to the sibling set_device_custom_attribute makes its role in the workflow unambiguous, though it does not explicitly distinguish itself from other list_* siblings such as list_tags.

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?

Clear usage context: it exists to supply the IDs needed by set_device_custom_attribute, which implies 'call this first to discover the attribute ID'. It stops short of explicit exclusions (e.g., that it returns definitions, not per-device values) or stating there are no parameters to filter by.

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), and the description adds genuinely new behavior: the shape of the returned summary and the non-obvious rule that retired devices are silently filtered unless include_retired or status is supplied. That silent-filtering default is exactly the kind of hidden behavior an agent needs. It stops short of describing pagination behavior or total-count semantics.

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 sentences, front-loaded with purpose, then return shape, then the exclusion rule and the sibling routing hint. Every sentence carries information not present elsewhere; nothing is padding.

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 13-parameter read tool with no output schema, the description compensates well by enumerating the summary fields and calling out the filtering default. Pagination behavior across page/rows and any result-count or truncation semantics are left implicit, which is the only 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 baseline is 3, but the description goes beyond restating fields by explaining the cross-parameter interaction between include_retired and status, and by characterizing the returned summary fields. The default exclusion semantics are not expressible in the schema alone.

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 managed devices in Miradore') plus scope ('with optional filters'), and explicitly separates itself from get_device for single-device detail. An agent can distinguish it from siblings like query_miradore or list_suspended_devices 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?

Names one concrete alternative with the condition that selects it ('Use get_device for full details on one device') and states the default exclusion rule for retired devices with the parameters that override it. It does not, however, distinguish itself from other list-style or search-style siblings, so routing among the wider toolset still needs 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds useful behavior beyond that: results are ordered newest-first and scoped to 'recent' enrollments. It does not say how far back 'recent' reaches, what fields come back, or how paging interacts with that window.

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 ordering, then the usage hint and enum clarification. Nothing is padded and no sentence is redundant.

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

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

For a read-only list tool the annotations cover safety and there is no output schema to explain, which lowers the bar. Still, an agent cannot tell the default result window, whether an empty list means 'not enrolled', or what a row contains, which matters for the stated verification use case.

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 only 25%, so the description must carry the parameter burden. It expands 'DEP' into Apple Automated Device Enrollment, which is genuinely useful, but page, rows and user_email are left entirely undocumented in both schema and description, so the description fails to compensate for the coverage gap.

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 recent device enrollments') plus an ordering guarantee ('newest first'), which an agent can act on directly. It does not differentiate itself from nearby siblings such as list_devices or sync_apple_dep_devices, so the boundary between 'enrollments' and 'devices' 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?

Offers one concrete scenario ('confirming that a newly set-up device enrolled') and explains the DEP enum value, which is real when-to-use guidance. It gives no exclusions or named alternatives, so an agent choosing between this and list_devices/list_suspended_devices gets no routing help.

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, covering the safety profile. The description adds nothing beyond that: no indication of result volume, pagination, whether counts are truncated, or how 'suspended' is determined.

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

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

A single front-loaded sentence with zero filler. Nothing superfluous and nothing buried.

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

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

For a zero-param read-only list tool with full annotation coverage and no output schema, the definition is minimally sufficient. However, it omits whether results are paginated or bounded and does not point at sibling list tools for unfiltered queries, which would be cheap additions for a catalog of this size.

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 no parameter meaning for the description to supply. Baseline of 4 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 (suspended devices) with the vendor named, so the agent knows exactly what the tool returns. It does not explicitly contrast with the sibling list_devices, leaving the distinction to be inferred from the word 'suspended'.

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

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

No guidance on when to use this instead of list_devices or query_miradore, both of which could plausibly return device sets. There is no mention of prerequisites, scope limits, or the exclusion condition that selects this 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?

The annotations already declare that this is read-only, non-destructive, and open-world, so the description does not need to restate safety. It adds useful business context about what tags represent, but it does not disclose return format, pagination, authentication needs, or other behavioral details 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?

The description is two short sentences with no wasted wording. The core purpose is front-loaded, and the second sentence adds useful context 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?

For a zero-parameter, read-only listing tool, the description is largely complete: it says what is listed and why tags matter. It could add what is returned or how to use the result when selecting tags for device or user assignment, but the gaps are minor for this level of complexity.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description does not need to compensate for an input schema.

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

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

The description states a specific verb and resource: 'List all tags defined in Miradore.' It clearly identifies the scope as all defined tags, but it does not explicitly distinguish this listing operation from sibling tag-mutation tools such as add_device_tag or remove_device_tag.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. The statement that tags group devices and can drive policies provides domain context, but not actionable when-to-use or when-not-to-use 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 safety profile is covered. The description adds no behavioral context of its own: it says nothing about pagination, default page size, result caps, or ordering, all of which matter for a list operation that can return up to 500 rows.

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

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

A single front-loaded sentence with the resource and filtering behavior in the first clause and nothing extraneous. No wasted wording.

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

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

The tool is a simple read-only list with four optional parameters, so the bar is low, but the description omits that results are paginated (default page 1, 100 rows, max 500), which an agent needs to page results correctly. No output schema exists, so any note on return shape would have helped.

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 50%: the two filter parameters carry their own descriptions (exact email, name contains), while page and rows are undocumented anywhere. The description restates the filters available but adds no meaning beyond the schema, and does not compensate for the undocumented pagination parameters.

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 Miradore users") and adds a clarifying gloss that users are people devices can be assigned to, which disambiguates the resource. It does not distinguish itself from siblings such as create_user or get_user_device_identifiers, 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?

"Optionally filtered by email or name" implies when the filters apply, but there is no explicit when-to-use guidance, no statement of when to prefer a different sibling (e.g. query_miradore for broader search), and no mention of prerequisite steps.

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 real behavioural context beyond that: a query grammar (operators joined with and/or), the constraint that 'orderby' fields must also be selected, quoting rules for values with spaces, and an explicit pointer to the external API v1 spec for attribute names. It does not mention the 500-row cap or what an empty result looks like.

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 purpose then immediately the query grammar, in one dense paragraph with no filler. It is a touch run-on (select, filters and orderby rules strung together), but every clause carries operative information for building a query.

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 42-value enum, a free-form filter grammar and no output schema, the description covers the query syntax well but defers all attribute discovery to an external Miradore API v1 specification the agent may not have. It also says nothing about response shape (item list vs single object when 'id' is set) or pagination semantics, which matter for a general-purpose query tool.

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

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

Schema coverage is 71%, and the description compensates for the weakest parts by explaining the dotted-path syntax for 'select', the full operator vocabulary and quoting rules for 'filters', and the 'orderby' ordering restriction. Only 'page', 'rows' and 'id' are left to the schema, and those are self-evident with defaults and bounds.

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 ('Advanced read-only query against Miradore API v1') and positions itself as the catch-all for item types the specialised tools do not cover, listing examples (Category, Organization, Location, InvCertificate, ConfigProfileDeployment). An agent can tell this apart from list_devices/list_users/list_tags 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 fallback condition is explicit: use this for 'anything the other tools don't cover'. No exclusion is stated for the overlapping item types that ARE in the enum (Device, User, Tag, Location), so an agent has to infer when to prefer list_devices over this generic query. Clear context, but not a full when/when-not routing rule.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is largely covered; the description's only added behavioral fact is the Miradore-deployed precondition. It says nothing about whether removal requires the device to be online/check in, how long propagation takes, or how partial failure is handled. Note the mild tension between "Remove" and destructiveHint=false, though the operation is plausibly non-destructive because only the deployment link is removed and it can be redeployed (idempotent).

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

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

One short sentence with no filler; the scope constraint ("from a device") and provenance constraint ("that Miradore deployed") are both front-loaded in the only place they could be.

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

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

For a two-parameter mutation with full schema coverage and complete annotations, this is close to adequate, but it leaves out what an agent would want before calling: whether the profile must be currently assigned, what happens if the device is offline, and what a successful removal returns. No output schema exists to absorb those questions.

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 both parameters (device_id, profile_id) carry their own descriptions including how to obtain device_id from list_devices. The description adds no format, constraint, or relationship detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ("Remove") and resource ("configuration profile") scoped to a device, and adds the qualifier "that Miradore deployed," which distinguishes it from a generic profile deletion. It does not explicitly name the inverse sibling deploy_config_profile, but the intent is unambiguous.

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

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

The phrase "that Miradore deployed" implies a precondition (only profiles previously pushed by Miradore can be removed), but there is no explicit when-to-use guidance, no mention of deploy_config_profile as the inverse operation, and no stated prerequisites such as the device needing to be reachable or the profile needing to be currently assigned.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=true, so the safety and repeat-call profile is covered elsewhere. The description adds useful scope context by clarifying that what is removed is an identifier such as a serial number, not the device itself. It does not say what happens when the identifier is not currently assigned, nor whether the device record is affected.

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

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

A single short sentence that front-loads the action and resource, with no wasted wording. It is lean to the point that it omits any routing or failure information.

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

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

For a two-parameter mutation with no output schema and reasonable annotation coverage, the definition is minimally adequate. It leaves out error behavior (identifier not assigned), confirmation of the idempotent semantics in prose, and any note on side effects to the device.

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 only 50%: 'email' is documented in the schema but 'identifier' has no schema description. The description partially compensates by explaining that the identifier is a pre-assigned device identifier such as a serial number. It still does not state the accepted identifier formats or whether it must match an existing assignment.

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 pair (remove a pre-assigned device identifier from a user) and clarifies the resource with an example ('e.g. serial number'). It is distinguishable from the inverse sibling assign_device_identifiers_to_user, 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?

There is no when-to-use or when-not-to-use guidance and no reference to the obvious alternative (assign_device_identifiers_to_user) or to remove_device_tag / remove_user_tag. The agent must infer the use case purely from the tool name.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and repeat-call profile is fully covered structurally. The description adds nothing beyond that — it does not say whether the tag is removed only from this device or purged globally, nor what happens if the tag is absent.

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

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

The single sentence is front-loaded and free of waste, but its brevity stems from under-specification rather than disciplined editing. Nothing is redundant because nothing beyond the title is stated.

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

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

For a simple two-parameter mutation with full schema coverage and rich annotations, the description does not need to explain return values. However, it should at least clarify whether the tag persists on other devices and reinforce the idempotent no-op behavior, which the annotations only imply.

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 'device_id' explicitly pointing to list_devices and 'tag' documented as a tag name, so the schema carries parameter meaning. The description contributes no additional syntax, format, or validation context, so baseline 3 applies.

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

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

The description names a specific verb and resource ('remove a tag from a device'), which is clearer than a pure tautology, but it offers no differentiation from the near-identical sibling remove_user_tag or any hint about scope. An agent must infer from the name and schema alone that this targets devices rather than users.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the complementary add_device_tag or remove_user_tag siblings. The only signal that this is an untagging operation is the verb in the description itself.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the description has a lower bar but adds nothing at all. It does not say what happens when the tag is absent on the user (relevant given idempotentHint), whether errors are raised, or what state the user record is left in.

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

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

The single sentence is front-loaded and free of padding, but for a two-parameter mutation tool it is undersized rather than genuinely concise — brevity here comes from omitted information, not efficient phrasing.

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

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

For a write operation with 50% schema coverage and no output schema, the description should cover the tag identifier format and the no-op/error behavior on a missing tag. It covers neither, leaving the agent to guess at the one parameter the schema leaves undocumented.

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

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

Schema description coverage is only 50%: 'email' is documented in the schema but 'tag' has no description beyond minLength 1. The description could have clarified whether tag is a name, ID, or case-sensitive label, and it does not compensate for that gap.

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 sentence 'Remove a tag from a user' restates the tool name (remove_user_tag) and title (Remove tag from user) almost verbatim, adding no scope, qualifiers, or detail beyond the identifier. It does not distinguish this from siblings such as remove_device_tag, add_user_tags, or list_tags.

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

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

No when-to-use guidance, prerequisites, or alternatives are given. The agent is left to infer from the name alone that this is the tag-removal counterpart to add_user_tags on the user resource rather than the device variant.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and repeatability profile is covered structurally. The description adds nothing beyond that — it does not restate that repeated calls are safe, nor explain effects such as empty-string clearing (left to the schema) or permission requirements. Adequate but thin given annotations do most of the work.

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 front-loaded, with the discovery hint immediately after. No filler, no redundancy — every clause earns its place.

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

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

For a simple three-required-parameter mutation with no output schema and rich annotations, the definition covers what the tool does and where to get the undocumented ID. Only minor gaps remain: no statement of return behavior or permission requirements, which the annotations largely imply.

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

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

Schema coverage is 67%: value and device_id are documented in the schema, while attribute_id has no schema description. The description partially compensates by pointing to list_custom_attributes as the source of attribute IDs, which is the one genuinely missing piece, but adds no format or semantics for the value payload 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?

The description names a specific verb and resource ("Set a custom attribute value on a device"), which is unambiguous and distinguishes it from read-oriented siblings like list_custom_attributes or get_device. It stops short of differentiating itself from other mutation siblings such as update_device or add_device_tag.

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?

"Find attribute IDs with list_custom_attributes" gives a concrete prerequisite step and routes the agent to the right sibling for discovery. However, it offers no guidance on when to prefer this over updating a device or adding a tag, 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?

Beyond the annotations, the description adds that Miradore rate limits this operation to once per minute and that assigning an enrollment profile to synced devices must still be done in the Miradore console. That is useful operational context not already covered by the readOnly/openWorld/idempotent/destructive annotations. It does not describe the sync response or failure behavior.

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

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

The description is short and front-loaded: the immediate sync purpose comes first, followed by the rate limit and the console limitation. Every sentence adds useful operational information without repetition.

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

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

For a single-parameter sync tool with annotations and no output schema, the description supplies the important constraints: on-demand scope, rate limit, and the console-only enrollment-profile step. It is nearly complete, though it could say what the sync returns or how update_all affects the result.

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

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

The input schema already has 100% description coverage for the only parameter, update_all, explaining that it re-syncs all devices rather than only changes. The description itself adds no parameter-level meaning. With high schema coverage, a 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 and resource: pull the latest device list from Apple Business/School Manager via Automated Device Enrollment/DEP. It also distinguishes the action from the scheduled sync by saying it runs 'now instead of waiting.' An agent can tell this is an explicit sync trigger, not one of the list/get 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 description clearly says when to use it: to pull the latest Apple device list immediately rather than waiting for the scheduled sync. It also notes the rate limit and the console follow-up step. It does not name explicit alternatives or when-not conditions, so it falls short of a full usage-guidance score.

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=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely non-derivable behavior: PATCH-like semantics where omitted fields are preserved. It still says nothing about permission requirements or side effects of reassigning a user, which keeps it below a 5.

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

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

Two short sentences, front-loaded with the mutable field list followed by the update-semantics constraint and the sibling hand-off. Nothing is redundant or buried.

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

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

For a 7-parameter mutation with no output schema, the definition covers what can be changed and how partial updates behave. The remaining gap is result/return behavior and coupling between ownership and its date fields, which is minor given annotation coverage.

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

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

Schema coverage is 71%, and the description only echoes the four field groups already documented in the schema. It adds no meaning for ownership_start_date / ownership_end_date, which carry no schema description at all, so an agent gets no guidance on when those are required alongside ownership.

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 ('Update a device') and enumerates the mutable fields (assigned user, friendly name, ownership, category), which lets an agent distinguish it from neighbours like activate_device, set_device_custom_attribute or assign_device_identifiers_to_user.

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 usage context: it is a partial update ('Only the fields you give are changed') and explicitly routes tag operations to add_device_tag / remove_device_tag. It stops short of naming when to prefer update_user-style reassignment or other siblings, so it is clear but not exhaustive.

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

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

Annotations already declare that this is a non-read-only, idempotent, non-destructive, open-world operation. The description adds useful behavioral context beyond those annotations: the user is looked up by email, email cannot be changed, and only name/phone fields are updateable. It does not state whether omitted fields are preserved or what happens when the user is not found, so it falls short of full transparency.

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

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

The description is a single, front-loaded sentence with a compact parenthetical constraint. Every part earns its place by stating the action, scope, lookup key, and immutability rule.

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 update mutation with annotations covering safety and idempotency, this is minimally adequate. However, the low schema coverage leaves the name-field parameters and partial-update semantics underspecified, and the lack of an output schema means the description could say more about the result of a successful or failed update.

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 only 20%, with just the email parameter documented. The description compensates partially by clarifying that email is the lookup key and immutable, and that name/phone are the updateable fields, but it does not explain the roles of first_name, last_name, middle_name, or partial-update behavior for omitted parameters.

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 ('Update an existing Miradore user'), names exactly what can be changed ('name or phone number'), and specifies the lookup key ('by email'). It also distinguishes itself from create/list user tools by emphasizing 'existing' and that email itself cannot be changed.

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 for modifying an existing user's name or phone number and notes that email is immutable. However, it does not explicitly route the agent away from create_user for new users or mention sibling tools for tags/device identifiers, so the when-to-use guidance remains implied rather than explicit.

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