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

With no annotations provided, the description carries the full burden. It discloses the tool's asynchronous behavior (status first, result when finished), the decrypted nature of the result, the long-poll capability up to 60 seconds, and the expected output components (status, result text, timeline). This is rich behavioral context, though it omits error handling, auth, and rate-limit details.

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

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

Three sentences, each earning its place: purpose, usage condition, and output summary. The most relevant information is front-loaded, with no filler or repetition of schema details.

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?

Given there is no output schema, the description compensates by spelling out the return content (status, result text, timeline) and the state transitions. It also references the companion tool askew_run and the condition that triggers this call. It stops short of covering edge cases like invalid job ids or terminal failure states, but for this tool's moderate complexity it is nearly complete.

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

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

Schema coverage is 100%, and both parameters already have helpful descriptions (jobId from askew_run, wait with 0-60 range and default). The description adds 'Set wait to long-poll up to 60 seconds', but this largely mirrors the schema's 'Seconds to long-poll for a terminal status'. It does not meaningfully extend the parameter semantics 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?

The description names a specific verb ('Return'), a specific resource ('the current status and, when finished, the decrypted result of a job'), and ties it to askew_run. This clearly differentiates it from sibling tools, especially askew_run, by defining it as the follow-up/status retrieval counterpart.

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 explicitly states when to use the tool: 'Use it when askew_run returned status unknown or pending'. It also gives a concrete example (wait=0 or slow phone) and explains how to configure the wait parameter. It lacks an explicit 'do not use when...' or named alternative, but the condition is clear enough.

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?

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses irreversibility ('cannot be undone'), the per-item nature of acknowledgement, persistence in phone history, and the return value. It does not cover error handling for invalid ids, but the core mutation behavior is transparent.

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 three tight sentences with no filler. It front-loads the primary effect, then delivers usage guidance, caveats, and return value in a logical order. Every sentence earns its place.

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

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

For a one-parameter mutation tool with no output schema, the description is complete: it explains what the tool does, where the ids come from, that the action cannot be undone, that items persist in phone history, and what the return value is. The only unaddressed area is partial failure behavior, which is a minor gap.

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

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

The schema already covers 100% of the single parameter, so the baseline is 3. The description adds meaningful guidance beyond the schema by instructing the agent to pass ids exactly as shown in inbox output and clarifying that acknowledgement is per item. This is useful operational context.

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 specific verb and resource: 'Mark inbox items as handled' and explicitly distinguishes itself from askew_inbox_list and askew_inbox_wait by stating they will stop returning acknowledged items. This makes the tool's role unambiguous among its 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 gives clear context for when to use the tool: to acknowledge items so list and wait operations no longer return them. It also provides a practical usage hint ('Pass the ids exactly as shown'). It does not explicitly list alternatives or exclusions, but there is no competing ack tool among the siblings.

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

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

With no annotations provided, the description carries the full burden and excels. It discloses that items are decrypted, returned immediately, retained until acknowledged, and that 'data is explicitly framed as user-phone data, not instructions'—a critical safety trait for an agent handling untrusted input. This goes far beyond typical descriptions.

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 information-dense yet every sentence earns its place. It front-loads the core purpose, then item types, return fields, safety framing, and behavioral details. There is no redundancy or filler.

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

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

Despite lacking an output schema, the description enumerates the exact return fields (id, kind, ref, timestamp, device, data) and explains retention semantics. Combined with the parameter documentation and behavioral notes, an agent has everything needed to call this tool 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?

The schema already documents `since` with 100% coverage, so the description need not repeat it. The added phrase 'Use `since` to skip older items' is a practical hint but does not introduce new semantic meaning beyond the schema's description of ISO 8601 timestamps and default behavior.

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 opens with a specific verb and resource: 'Return items the phone sent to the agent' and enumerates the item types (automation triggers, share-sheet shares, voice memos, Shortcut posts). This precisely differentiates it from siblings like askew_inbox_ack (acknowledge) and askew_inbox_wait (wait for items).

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 states behavior that guides selection: 'returns immediately (no waiting)' contrasts with askew_inbox_wait, and 'items stay listed until askew_inbox_ack is called' explains when to use the sibling ack tool. It also explains when to use the `since` parameter. It doesn't explicitly name the alternatives, but the usage context 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?

With no annotations, the description carries the full burden. It clearly discloses blocking behavior, timeout semantics ('Returns 'inbox empty' on timeout without error'), early return, and the need to acknowledge items to avoid duplicates. This fully informs the agent of the tool's side effects and loop usage.

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 concise and front-loaded with the primary behavior, then adds usage and acknowledgment notes. Each sentence earns its place—no fluff. The structure is logical: behavior, usage, timeout handling, and follow-up action.

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 blocking tool with no output schema, the description fully explains what to expect (returns like askew_inbox_list), timeout behavior, and how to properly handle items (ack). An agent can call this correctly without additional information. The reference to askew_inbox_list is acceptable since it's a sibling 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 description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond the schema (e.g., it repeats the timeout range but doesn't explain 'since' beyond what's in the schema). It does add behavioral context about looping and acknowledgment, but that's not parameter semantics. Thus a 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 (block/wait) and resource (inbox item), and explicitly distinguishes from askew_inbox_list by noting it returns the item exactly like that tool. It also names askew_inbox_ack for acknowledgment, making its purpose 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 description provides clear usage context: 'Use this in a loop to react to the phone in near real time' and instructs to call it again on timeout. It also mentions the ack tool for handling items. However, it doesn't explicitly contrast with askew_inbox_list (e.g., 'use list instead if you don't want to block'), so the guidance is strong but not fully explicit about when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses what the tool returns in detail, states that it takes no arguments, and positions it as an inspection step before execution, implying no side effects. It stops short of explicitly stating that it does not modify state or describing failure behavior, but for a list operation these are minor gaps.

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 front-loaded with the core purpose and then provides a dense but purposeful enumeration of returned fields and usage guidance. Every sentence adds value, with no filler or 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?

With no output schema and no annotations, the description compensates by enumerating every category of returned data and explaining the field-level semantics, including inputExample, input hint, and output hint. It also tells the agent what to do when a route lacks a contract, making it complete for safe invocation.

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 is empty and schema description coverage is 100%, so the baseline is 4. The description reinforces this by explicitly saying 'Takes no arguments,' leaving no ambiguity about invocation.

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

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

The description states a specific verb ('List') and a clear resource ('everything an agent can act on in this account'), then enumerates the exact contents: connector details, devices, and routes. It also distinguishes itself from the sibling askew_run by framing this as the discovery step before execution.

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 explicitly instructs the agent to call this before askew_run to learn the exact input keys a route expects. It also provides a clear conditional behavior: if a route shows no contract, ask the user what the Shortcut expects before running it.

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

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

With no annotations, the description carries the full disclosure burden and succeeds: it reveals one-way delivery, Apple Watch mirroring, clear-text `title`, end-to-end encryption for `body` and `content`, and that delivery ids are returned. These are behavioral facts an agent needs beyond the schema.

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

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

Four dense sentences front-load the core action and then layer security, field guidance, return value, and grouping without filler. Every sentence earns its place.

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

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

Given the tool's complexity, no annotations, and no output schema, the description is remarkably complete: it covers routing, encryption, one-way nature, return value, and `ref` grouping. The only omitted details, like auth or error behavior, are not essential for an agent to call this notify tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces role distinctions between `body` and `content` and warns about `title` being clear text, but these are already present in the schema's parameter descriptions—so the added semantic value is modest.

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 opens with a specific verb and resource: sending a lock-screen notification to the user's phone and keeping full text in the app's results box. It clearly separates this send-oriented tool from the sibling inbox tools by framing it as one-way agent-to-person communication.

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 explicitly states when-not to use this tool ('the user cannot reply through it') and names the alternative for the opposite direction ('to receive data from the phone use the inbox tools'). It also gives practical field-selection guidance: use `content` for long text and `body` for the short lock-screen line.

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?

With no annotations provided, the description carries the full burden and meets it impressively. It discloses locked-phone execution, end-to-end encryption, rejection of mismatched input before any run, wait/polling behavior, status values, and the meaning of idempotencyKey for retries.

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 dense but every sentence adds necessary operational detail, and it is well structured with purpose first, then behavior, then usage guidance. There is no filler or redundant repetition of schema fields.

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 complex async execution tool with no annotations and no output schema, the description is remarkably complete: it explains how results arrive, what statuses to expect, how to poll, how to handle failures, and how to retry safely. Nothing critical is missing for correct invocation.

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?

Although schema coverage is 100%, the description adds meaning beyond the schema: input must use exactly the route's example keys with 'YYYY-MM-DD HH:mm' dates, empty strings for unused keys, routeId precedence over routeName, and the recommended use of idempotencyKey for network-error retries.

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 opens with a specific verb and resource: "Run a Shortcut (a 'route') on the user's iPhone, iPad or Mac and return its result." It clearly separates this from sibling tools by naming askew_list_routes as a prerequisite and askew_get_run for polling, so an agent can tell what this tool is for.

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 explicit when-to-use guidance: call askew_list_routes first, match input to the route's inputExample, and poll with askew_get_run when status is 'unknown' or 'pending'. It also gives when-not-to-retry guidance: don't blindly retry a failed job, read the error and fix the input.

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?

With no annotations provided, the description carries the full disclosure burden and meets it: it explains the end-to-end encryption model (values sealed with an account key, relay cannot read them, connector decrypts locally), states exactly what is returned (value text and last-updated timestamp), and enumerates three error conditions with a concrete remediation for the most likely one. This goes well beyond what structured fields would provide.

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

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

Four short sentences are front-loaded with the core action ('Read a variable...') before layering security context, return value, and error handling. Every sentence earns its place — no filler, and the error block is structured as an actionable list.

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 tool with no output schema and no annotations, the description covers everything needed to call it correctly: purpose, value semantics, security model, return contents, and failure modes. The only minor gap is remediation for the old-format error, which an agent can readily infer from the askew_variables_set sibling.

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 name parameter already documented as case-sensitive, with examples and provenance, so the baseline is 3. The description adds value above baseline by explaining what kinds of content variables hold (location, plan, preference), reinforcing the semantics beyond the schema's formal constraints.

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 ('Read') and resource ('a variable shared between the agent and the user's phone') with illustrative examples (location, plan, preference). The get/set naming plus the schema's explicit cross-reference to askew_variables_set clearly distinguishes it from its sibling setter, and it does not overlap with the other run/inbox/notify 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?

Usage is implied by the purpose — it reads a shared variable — and the schema names askew_variables_set as the writer, but the description itself gives no explicit when-to-use versus when-not-to-use advice. Error remediation is provided for the missing-account-key case, but there is no guidance for the name-not-found or old-format errors, and no alternatives are excluded.

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?

With no annotations, the description carres the full burden — and it delivers: encryption before leavg the computer, relay stores only ciphertext, overwrite-on-existing-name with no versioning, return values, and an actionable error case with user remediation steps. Exemplary beavioral disclosure.

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

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

Every sentence carries distinct information: purpose, security model, overwrite beavior, return value, error handling, and usage limits. The purpose is front-loaded and nothing is redundant or filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers all decision-relevant aspects: what it writes, how it protects data, what happens on conflict, what it returns, how to handle the key-not-arrived error, and suitable payload sizes. Nothing an agent needs to call 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 description coverage is 100%, so the baseline is 3; the schema already documents name (case-sensitive, overwrite beavior) and value (string or JSON object, encrypted). The description reinforces these facts but adds little parameter-specific meaning 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?

Opens with a specific verb-resource statement — 'Write a variable shared between the agent and the user's phone' — so an agent knows exactly the operation and resource. The write operation is clearly distinct from sibling askew_variables_get and the run/inbox tools.

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 context — 'Use it for data a Shortcut should pick up later (e.g. 'today.plan')' — and an exclusion ('not for large blobs'). It does't explicitly name askew_variables_get as the read counterprat, so the when-not-to-use guidance is slightly less direct than it could be.

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