Thumble

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description's only added disclosure is a scope caveat ('does not prove Mac input or game bindings'), which is too vague and jargon-laden to be actionable, and it never says what 'rendered' actually returns or guarantees.

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 short but not front-loaded: the leading sentence is a vague instruction and the remaining sentences read as caveat fragments with unexplained terms ('rendered', 'Mac adoption'). Brevity here reflects under-specification rather than economy.

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

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

With no output schema, the description is the only place to explain what a status/rendering result contains, and it does not. Combined with an undocumented required identifier, an agent lacks the information needed to call this correctly or interpret the response.

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

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

There is one parameter (deliveryId, required, regex-constrained) with 0% schema description coverage, so the description must compensate, but it never mentions the identifier or what form of delivery it refers to. The description contributes nothing to parameter meaning.

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 name says delivery_status but the description talks about 'reading the phone receipt' and 'rendered confirms the exact phone layout', so the verb/resource pairing with the tool name is never made explicit. An agent cannot tell whether this retrieves a delivery, validates a rendering, or inspects device layout, and no sibling is distinguished.

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 exclusion conditions, and no reference to alternatives such as list_devices or list_profiles. The clause 'after explicit Mac adoption' hints at a context but never states it as a selection 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely new behavioral fact — omitting revision silently returns the latest saved revision — but says nothing about failure modes for unknown or draft-only profileIds.

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

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

Two short sentences, zero waste: the purpose and the read-before-edit cue come first, then the parameter default behavior. Nothing could be removed without losing information.

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

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

For a two-parameter read with no output schema, the description covers the call mechanics but not the result — the agent has no idea what a 'controller' document contains or how to interpret it, which matters given the sibling profile_schema exists for that purpose.

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 0%, so the description must carry parameter meaning; it explains revision fully (omit for latest, otherwise a specific revision number). It adds nothing about profileId beyond the pattern constraint, leaving the most important identifier undocumented in both places.

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?

"Read a controller" gives a verb and a resource, but the resource is called a 'controller' while the tool and its sibling list_profiles talk about 'profiles', so the agent has to bridge that naming gap. It doesn't state that a full profile document is returned or how this differs from list_profiles, leaving differentiation 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?

"Read a controller before editing" implies a read-before-write workflow, which is useful context for when to call it. However, there is no explicit alternative named (e.g., list_profiles to discover profileId, or profile_schema to understand the document) and no statement of when this tool should not be used.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds useful context beyond that: it enumerates the returned fields and explicitly states that device credentials are never returned, which matters for an agent reasoning about data exposure.

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

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

Two short sentences with zero waste. The content description comes first and the security caveat second, both earning their 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 list tool with strong annotations, the description covers what is returned and the credential exclusion. It does not mention pagination or result formatting, 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 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 (registered phones, viewports, last-seen times) scoped to 'this account.' The device focus implicitly separates it from list_profiles/get_profile, 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 implied by the purpose—call it to enumerate this account's devices—but there is no explicit when-to-use guidance or comparison against siblings like delivery_status or show_pairing_code.

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, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description's one added fact is that results include 'latest revisions', which tells the agent something about payload shape, but it says nothing about ordering, result limits, or failure modes for an empty account.

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 scope qualifier ('this account's') and the content qualifier ('latest revisions') both earn their place.

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

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

With no parameters and no output schema, the description does the main remaining work of telling the agent what comes back (controllers plus their latest revisions). It stops short of describing result volume or ordering, which would matter for a list endpoint with no pagination controls.

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 disambiguate and the baseline is 4. It could have noted there is no filtering or pagination (all saved profiles are returned), but the absence of parameters makes this a minor 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 ('List') and resource scope ('this account's saved controllers and latest revisions'), which lets an agent distinguish it from the singular get_profile sibling. The only wrinkle is terminology drift: the tool is named list_profiles but the description says 'controllers', requiring the agent to infer these are the same objects.

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 indication of when to use this versus get_profile or profile_schema, and no stated exclusions or prerequisites. The agent must infer that a parameterless 'list' is the enumeration counterpart to the singular 'get', which is reasonable but left entirely implicit.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful domain context beyond annotations by clarifying that profiles contain layout data only and cannot send game input, which helps prevent misuse.

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 language. The core purpose is front-loaded, followed by a useful constraint.

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

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

For a simple, zero-parameter, read-only schema retrieval tool, the description is nearly complete. It states what is returned at a high level and adds a key limitation, though it does not further describe the schema structure or return shape.

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 is no parameter semantics to explain. Per the scoring rule, a zero-parameter tool receives a baseline of 4.

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 uses a clear verb+resource: 'Get the controller schema and design constraints.' It is specific enough to distinguish this schema-retrieval tool from profile retrieval, but it does not explicitly name or contrast with siblings such as get_profile or list_profiles.

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

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

Usage is implied by the purpose statement, and the caveat that profiles cannot send game input adds useful context. However, there is no explicit when-to-use guidance or direct comparison to alternatives like get_profile or list_profiles.

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, idempotent, non-destructive, closed-world, and the description adds substantive context beyond them: the credential is single-use and temporary, the operation neither disconnects a phone nor sends gameplay input, and the QR must never be published. That is exactly the extra behavioral disclosure a safety-sensitive tool needs.

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-loads the core action and follows with prerequisites, defaults, and safety constraints in a logical order. Slightly dense and fragmented by ellipses, and the network requirement could be merged into the prerequisites sentence, but nearly 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 one-optional-param, read-only tool with annotations and no output schema, this covers preconditions, multi-device selection, network constraints, and safety. The remaining gap is QR lifetime/expiry behavior and what the caller should do if pairing fails, which are not addressed.

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 0% and the receiverId pattern is only in the schema, so the description must carry the meaning. It does explain what receiverId selects (a specific sharing Mac/receiver) and when to ask the user for it, though it never describes the identifier's form or how to obtain a valid value beyond the in-app Pair menu.

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 (display a single-use pairing QR image inline in ChatGPT) plus the exact scope of what it returns. It is unmistakably distinct from siblings like list_devices, delivery_status, or profile_schema, and an agent can route to it 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 explicit preconditions (Mac owner must choose Pair in the receiver menu and sign in to the same account), the default call pattern (no arguments for one sharing Mac), and the branch for multiple Macs (ask the user which receiverId). It also names the environmental requirement that both devices share local Wi-Fi.

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