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

Since no annotations are provided, the description bears the full burden of disclosing behavioral traits. It does well by explaining the dual behavior (live call vs. ended call), the requirement for short spoken sentences, and that the answer is read aloud potentially on a live call. However, it does not mention any authentication needs, rate limits, or potential side effects (e.g., what happens if the notificationId is invalid or the call state is ambiguous), which would push it to a 5. It also lacks details on expected output format, though no output schema exists.

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 first sentence immediately stating the core purpose and context. Every sentence provides essential information: when to use, behavior based on call state, and output format constraints. No wasted words.

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 moderate complexity (2 params, no output schema, no annotations), the description is complete. It covers purpose, usage guidelines, behavioral nuances, parameter semantics, and output characteristics. The context signals indicate no other complex requirements like enums or nested objects, so the description adequately addresses all essential aspects.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the purpose context for 'answer' (short spoken sentences, may be read aloud) and linking 'notificationId' to the call that carried the caller's question, derived from a partial turn or settled reply. This goes beyond the schema's basic descriptions, but does not add constraints like allowable length in seconds or any validation rules, leaving a small 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 description clearly states the tool answers a question asked by a user during a live call. It specifies the verb 'answer' and the resource 'caller_question', and distinguishes it from siblings like 'await_reply' or 'handoff' by emphasizing the live-call context and the dual output mechanism.

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 says when to use the tool: when a partial turn or settled reply carries a 'question' intent aimed at the agent during a live call. It also clarifies two distinct scenarios—if the call is still live (answer spoken on the call) versus if it ended (send as threaded contact), and warns against dropping the answer. This provides clear context and exclusions, such as not for non-question intents.

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 full burden and delivers thoroughly. It explains the polling mechanism (45s default, under 60s cap), all possible return types (reply, remind, idle, partial, call answer), their meanings, and how to respond. It also covers scoping, concurrency behavior, Paigy's lack of scheduler, and nuances like intents and points. No behavioral aspect is left unclear.

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 extremely long and lacks structural elements like bullet points or sections. While every sentence adds necessary detail, the sheer volume makes it harder to parse quickly. It is front-loaded with the core purpose but then expands into a dense block of text. A more structured format would improve readability without sacrificing completeness.

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 (polling, multiple return types, partials, call handling, intents, points, concurrency) and the absence of an output schema, the description is remarkably complete. It covers all scenarios, edge cases (idle, partial, call answers), and actionable instructions for each. An agent can understand the full lifecycle of using this tool without additional context.

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%, but the description adds significant value beyond the schema. It explains the default of maxWaitSeconds (45s) and why it's set that way, warns about host caps, and clarifies that notificationId comes from the contact tool. This context helps the agent use parameters correctly without guessing.

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 clearly states the tool's purpose: 'Wait for the user's reply to a specific notification you sent.' It uses a specific verb ('wait for') and resource ('reply to a notification'), and distinguishes itself from the sibling tool 'contact' (which initiates the notification). This is precise and 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 offers extensive guidance on when to use this tool: after sending a notification, how to loop on idle, when to use schedule_callback or contact for follow-ups, and how to handle partials. It explicitly tells when not to treat partials as final and advises against giving up after one window. Alternatives like schedule_callback and contact are mentioned with specific contexts.

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 burden, and it does so thoroughly: it declares the call is a PURE read, takes no arguments, is safe to call often, and that nothing is consumed by reading. It also discloses important non-obvious behavior: entries reappear until acknowledged, set_task_state claims them, and identity discovery via pair can mint a new identity.

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 most important facts and contains dense, useful operational detail, but it is an extremely long single paragraph with many parenthetical asides, capitalized emphases, and nested clauses. Every sentence adds value, but the lack of structure makes it harder to scan and parse than an ideally organized description.

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

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

There is no output schema, so the description must explain the return contract, and it does: it enumerates every returned category, explains how to handle each (threads, owedCallbacks, also, stalled, you, stranded, intents/transcript/covered), and ties processing back to set_task_state and contact. This is more than enough for an agent to invoke and interpret the 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 tool has zero parameters and the schema already documents that with 100% coverage. The description explicitly reinforces this by saying 'takes no arguments,' so no additional parameter semantics are needed. The baseline of 4 for zero-parameter tools 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 opens with a clear and specific purpose: 'catch-up sweep for everything outstanding' and then enumerates the distinct return groups (replies, pending notifications, requests, threads, owedCallbacks, stalled, you). It also differentiates itself from siblings by explicitly routing await-reply use to await_reply and identifying set_task_state as the claiming mechanism.

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 when-to-use instructions: 'Use check_replies when booting up / starting a session, or when you've been waiting a long time on something else,' and explicitly says to use await_reply instead when waiting on a specific contact call. It also provides detailed operational rules like working one thread at a time and leaving busy threads alone.

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

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

With no annotations provided, the description fully discloses the tool's behavior. It explains the return structure ({ notificationId, parentId }), the 'ifMissed' field, the 'units' field, 'kind:clarify' responses, the 'plan.units[].needs' scenario, and the threading behaviors (replace, escalate). It also warns about the 'DONE IS SAID ONCE' rule and the 'ONE ASK, ONE ROW' constraint, leaving no ambiguity about how the tool operates.

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 dense wall of text containing critical information, but it lacks structure and is overly long. It could benefit from sections (e.g., 'Return values', 'Threading', 'When to use') and more concise phrasing. While every sentence is valuable, the format makes it harder for an AI agent to parse quickly.

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 (5 parameters, 1 required, enums, no output schema), the description covers all necessary context: return values, threading, error handling (clarify, needs), waiting semantics, and the 'units' reporting. It explains the tool's interaction with the user and the Paigy system thoroughly, leaving no gaps for an AI agent to guess.

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 provides 100% parameter descriptions, but the tool description adds significant behavioral context. For 'ask', it elaborates on the two allowed moments and the 'DONE IS SAID ONCE' rule. For 'waiting', it explains the enum values in action ('hard' escalates to a call). For 'parentId', it details threading rules. For 'options', it connects to the 'needs' clarification scenario. This goes well beyond the schema's minimal descriptions.

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 immediately states the tool's purpose: 'Reach the user through Paigy — tell them something, or ask and get their answer.' It clearly distinguishes from sibling tools like await_reply, set_task_state, and schedule_callback by explaining how they relate (e.g., 'pass notificationId to await_reply for the answer') and when not to use contact ('Progress is never a contact').

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 explicit when-to-use guidance ('Contact at exactly two moments: BLOCKED on a decision only they can make, or DONE') and when-not-to-use ('Progress is never a contact: set_task_state carries it'). It also covers threading rules (right for updates, wrong for checklists), channel selection, and waiting behavior, making alternative selection 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?

No annotations are provided, so the description carries the full transparency burden. It discloses the return format (turns with roles, fields), ordering (oldest first), capping (most recent 30), and the special meaning of 'handoff' and 'recap' turns. It does not mention authentication requirements, rate limits, or whether the tool is read-only (though it is clearly read-only). The lack of a read-only statement is a minor gap, but the overall transparency is high.

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 about 150 words, which is longer than ideal but justified by the complexity of explaining turn types and usage scenarios. It is front-loaded with the core purpose, then usage guidelines, then structure details. Every sentence adds value, but the density could be improved (e.g., by breaking into shorter sentences or bullet points). Still, it is well-organized and clear.

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 has only one parameter and no output schema, the description provides complete coverage: it explains when to use the tool, what the output contains (turns with roles and fields), ordering, capping, and the special semantics of handoff/recap turns. It even instructs the agent on how to interpret the turns ('read as prior conversation you were part of, not as new input'). Nothing essential is missing for an agent to use 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 input schema has 100% coverage: the single parameter 'parentId' is described as 'The thread to read — from a reply, request, or past notification.' The tool's description adds 'from a reply, request, or past notification' which is essentially the same as the schema description. It does not provide additional context like format, constraints, or examples. With full schema coverage, baseline is 3, and the description adds no significant extra value for the parameter.

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 clearly states the tool's purpose: 'The chronological transcript of one Paigy conversation thread — every past ask, answer, and user request on it.' It specifies the verb (get), resource (thread), and scope (chronological transcript). It also provides concrete usage scenarios (resuming, seeding) that distinguish it from siblings like search_threads, which would be used for finding threads rather than retrieving their full history.

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 this to REHYDRATE when you're resuming or being seeded... call get_thread FIRST and read the turns as prior conversation.' It explains the conditions that trigger this need (unrecognized parentId from check_replies, contextParentId) and what to do with the output. It does not explicitly mention when not to use it, but the context is so specific that alternative uses are clearly inappropriate.

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 clearly states that the tool does NOT ring the user or enter their inbox, and explains exactly what `recap` does to thread history. The only missing detail is whether the handoff note is persisted or transient, and whether there are any rate limits or permission requirements. Still, it is remarkably transparent about behavioral traits for a tool with no 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 a single paragraph of 160 words, which is on the longer side. It front-loads the core purpose in the first sentence, but then packs many conditional scenarios into a dense block. Every sentence earns its place—there is no fluff—but the structure could be improved with bullets or clearer segmentation for readability.

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 moderate complexity (5 params, no enums, no nested objects, no output schema), the description covers all essential use cases. The return value `parentId` is mentioned. The `recap` behavior is thoroughly explained. The only missing element is a note about what happens to the handoff note if the target agent is offline or busy, or error conditions.

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 compensate entirely. It covers all 5 parameters: `target` (handoff recipient), `parentId` (thread context), `recap` (rehydration behavior), `title`, `notes` (content). It adds semantic meaning beyond the raw schema—e.g., explaining the effect of omitting vs including `target`, and the advanced use of `recap`. One minor gap: `notes` array items are described as strings but no per-item formatting is mandated.

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 clearly states the tool's purpose: depositing working context as a note for a successor agent on a thread. It distinguishes between three modes—direct handoff to a specific agent (with `target`), leaving for user assignment (without `target`), and creating a fresh thread (with `parentId`). The verb 'deposit' plus resource 'context on a thread' is specific and differentiates it from siblings like `await_reply` or `get_thread`.

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 explicit guidance on when to use each parameter variant and even explains an advanced `recap` feature for rehydration. It tells the agent when to write a recap (thread grown long, handing off, near context limit) and what the side effects are. No alternatives among siblings are mentioned, but the context of 'handoff' vs 'await_reply' or 'answer_caller_question' is implicitly clear from the description.

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

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

Discloses idempotency, read-only behavior ('never writes settings'), and the special case where enable_command cannot be applied by the tool itself. Lacks explicit mention of what happens if name/voice are provided when already set up without renaming.

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 and order-of-call directive. Dense with information but still readable; could be slightly more concise by splitting into bullet points for different scenarios.

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?

Covers all states (not set up, already set up, token invalid), expected outputs (user_code, enable_command, identity), and how to handle each. No output schema needed as return behavior is fully described.

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?

Describes name and voice purpose ('choose who you are when hatching, or RENAME yourself when already set up', voice examples given). Other parameters (scope, device_code) are not explicitly described, but the description provides usage context for device_code in the user_code flow.

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 clearly states the tool initializes identity with Paigy and covers all possible states (not set up, already set up, token invalid). It distinguishes from siblings like 'contact' and 'await_reply' by explicitly saying to call it first before those.

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?

Explicitly says when to call ('call it FIRST, before contact/await_reply, and any time you're unsure who you are') and provides clear instructions for next steps when user_code or enable_command is returned.

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 full burden. It fully discloses that the tool does NOT open a browser, starts polling in the background, returns specific fields (user_code, device_code, qr, user_message), and what happens on each outcome. It also warns about host blocking if the agent tries to run the enable_command. Every behavioral aspect is transparently documented.

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 verbose but well-structured. It front-loads the core purpose and fast-path, then builds into the code ceremony details. Every sentence serves a purpose, but some repetition (e.g., multiple mentions of printing) could be trimmed. For a complex two-path tool, the length is justified.

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 complexity (two paths, polling, enable_prompt, host restrictions) and the lack of an output schema, the description is remarkably complete. It covers both scenarios, the polling mechanism, all possible statuses, and the final enable_command workflow. No critical gaps remain.

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 baseline is 3. The description adds significant context beyond the schema: it explains that name and voice are only for the 'Hatch path', gives naming conventions, lists allowed voices, and clarifies that device_code should be passed from step 1. This extra guidance raises the score above baseline.

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

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

The description clearly states that the tool pairs the agent with a Paigy account, required before contact/await_reply work. It distinguishes two paths (fast path with device credential and code ceremony without), and implies its role relative to siblings like 'unpair' which reverses it. The verb 'Pair' matched with specific resource and prerequisite context makes the 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 explicitly states when to use the tool ('required before contact/await_reply work') and provides detailed step-by-step instructions for both the fast path and the code ceremony. It tells the agent exactly how to handle each status ('pending', 'awaiting_confirmation', 'paired') and what actions to take (printing user_message, calling again, printing enable_command). This is comprehensive usage 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?

No annotations provided, so description carries full transparency burden. It discloses that the callback persists even if idle, explains how triggers fire (e.g., 'fires when you call set_task_state completed'), and describes the lifecycle (pending until fulfilled via contact). Lacks details on cancellation or multiple callback behavior, but covers the core behavioral traits well.

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?

Description is three sentences, efficient and front-loaded with purpose. No redundant phrases. Could be slightly more structured (e.g., bullet points for triggers) but remains clear and concise.

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 4 parameters, no output schema, and no annotations, the description provides sufficient context for an AI agent to understand when to schedule, what triggers to use, and how to later fulfill the callback. Lacks explicit return value or error handling, but the tool's behavior (scheduling) is adequately described for use.

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 75% (3 of 4 params have descriptions). The free-text description adds meaning beyond schema by explaining trigger enum values and dueInSeconds usage ('e.g. remind me in 10 min'). For note and parentId, schema descriptions suffice; description supplements trigger and scheduled logic.

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?

Description clearly states tool's purpose: 'Promise the user a follow-up you'll keep even if you go idle.' It identifies the specific resource (callback/follow-up) and distinguishes it from sibling tools by explaining how to fulfill it (via contact) and list it (via check_replies).

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?

Explicitly states when to use: 'Use it when they ask you to report back.' Describes three trigger options with examples (on_done, on_blocked, scheduled with dueInSeconds). Also provides follow-up actions: 'Fulfill it by calling contact on that parentId; check_replies re-lists due callbacks until you do.'

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?

Even without annotations, the description fully discloses behavioral traits: it's read-only ('safe to call anytime'), scoped to the agent's own account, returns highlighted snippets (not row data), and describes the output structure explicitly. This goes beyond what annotations would typically cover, providing rich 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 concise yet packs significant value into a few sentences. It is front-loaded with the core purpose, then provides format details and usage loop. Minor redundancy (e.g., repeated emphasis on read-only) could be trimmed, but overall it's efficient.

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 single parameter, no output schema, and no annotations, the description is remarkably complete. It explains the tool's role in the workflow (search, get_thread, then continue), its output format (with detailed structure example), and its safe read-only nature. Nothing essential is missing.

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

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

The schema has 100% coverage with a clear description of the 'q' parameter. The description adds extra context by clarifying that the input can be 'plain words or a phrase' with examples, and that the search is full-text over past threads, which enhances understanding beyond the schema's description.

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 clearly states the tool's purpose: to search past conversations (threads) using full-text search. It distinguishes itself from siblings like 'get_thread' and 'contact' by specifying it returns ranked threads with snippets, not rows, and is meant for searching before rehydrating a thread.

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 explicit guidance on when to use this tool: 'search first → get_thread the best hit to rehydrate it → THEN continue or contact'. It explains the loop and contrasts with alternatives like 'contact' or 'await_reply', making it clear that search_threads is for retrieving past context before reaching out.

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

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

The description fully discloses behavioral traits beyond what annotations provide (none exist). It explains that calling this marks work as claimed, preventing re-appearance of notifications. It details the three states and links needs_input to a follow-up contact with clarifies parameter. It also explains cross-session behavior: if a prior session left work at in_progress without completing, a future check_replies will surface it as stalled.

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 packed with useful information in about 6 sentences, each sentence adding distinct value. While dense and front-loaded, it could be slightly more concise by splitting into bullet points or shortening some compound clauses. No waste, but the information density is very high.

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 (2 required params, enum, 12 sibling tools, no output schema), the description is remarkably complete. It explains tool purpose, precise usage timing, state meanings, consequences of not calling, pairing with other tools like contact and check_replies, and cross-session stall detection. No output schema exists, but the return value is not complex enough to require further explanation.

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% (no param descriptions in schema), so the description must compensate fully. It does so by explaining notificationId is the ID of the follow-up work behind a notification, and state enumeration is documented with specific meanings for each value (in_progress for started, completed for done, needs_input when more user input needed, with pairing guidance).

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 clearly states the tool is for reporting progress on follow-up work behind notifications the agent owns, specifying the verb (report progress), resource (notification), and scope (user-initiated requests or own contact questions). This effectively distinguishes it from siblings like check_replies, which is described as a 'pure read that never consumes anything on its own'.

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 explicit guidance on when to use this tool: immediately when starting to engage with returned items from check_replies, as it acknowledges/claims the item. It explains the consequence of not calling it (items keep reappearing forever). It also differentiates from check_replies, saying check_replies is a pure read and this tool does the actual consumption.

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 does an excellent job of disclosing all behavioral traits: it performs a destructive operation (revokes token, deletes local file), is irreversible in terms of current session (token stops working everywhere), and blocks dependent tools afterward. This fully compensates for the lack of structural 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 extremely concise at two sentences, yet it conveys the purpose, behavioral impact, and consequences for other tools without any wasted words. Every sentence adds critical 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?

Given zero parameters, no output schema, and a straightforward action (logout/unpair), the description is completely sufficient. It covers the action, the mechanism (token revocation, file deletion), the scope (globally effective), and the impact on sibling tools (contact/await_reply blocked). No gaps remain for an AI agent to make an incorrect decision.

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 (0 parameters), so there is nothing for the description to add semantically beyond confirming it takes no arguments. The description explicitly states 'Takes no arguments,' which is accurate and helpful. A score of 4 is appropriate as baseline for zero-parameter tools, though the clarity of the statement is commendable.

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 clearly states the verb 'Log out / unpair' acting on the resource 'agent from the user's Paigy account'. It elaborates on the action with technical details (revokes token server-side, deletes local file) and distinctively separates this from sibling tools like 'pair' and the communication tools it affects.

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 tells when to use this tool (to log out/unpair) and what the consequences are ('after this, contact/await_reply won't work'). It also mentions the prerequisite for reusing those tools ('until the user pairs again with the pair tool'), which serves as effective guidance on when not to use it and what alternative to use later.

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