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

Annotation Contradiction: destructiveHint=false conflicts with the description's explicit 'Delete completed batch ledgers' and 'removes local message text and file paths.' Although the description is transparent about retention and non-deletion of Telegram messages, the annotation says the tool is not destructive, which is misleading for an agent relying on 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?

Three sentences, each with a distinct job: action, retention rationale, and scope limitations. No filler or repetition; the most important information is front-loaded.

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 one optional parameter and no output schema, the description covers what is deleted, what is kept, and what is untouched. It is sufficient for an agent to invoke 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?

With 0% schema description coverage, the description carries the full burden and delivers. It explains the optional parameter's semantics ('explicitly supplied positive number of days'), the default behavior (configured retention period), and the threshold direction ('older than'). This adds meaning far beyond the bare 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 opens with a specific verb and resource: 'Delete completed batch ledgers' and adds precise conditions ('older than the configured retention period, or the explicitly supplied positive number of days'). This clearly distinguishes it from sibling batch tools like batch_status or preview_batch.

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: cleaning up completed batch ledgers by age. It also states exclusions — incomplete and unconfirmed attempts are retained, and it does not delete Telegram messages or attachment files — which tells an agent when not to use it. It does not name an alternative tool, but no cleanup sibling exists.

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 mark it read-only and idempotent; the description adds a non-obvious behavioral trait: unconfirmed status is not necessarily failure and automatic retry after crash/timeout is unsafe. This materially changes how an agent should act, which is exactly the kind of disclosure that matters.

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

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

Two sentences, front-loaded with the operation and parameter, followed by included fields and a critical caveat. No wasted words and all content 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?

With no output schema, the description usefully sketches the expected payload (roles, tags, metadata, Telegram ids, reply relationships) and gives the key operational caveat. It does not cover error/expiry behavior or explicit sibling routing, but for a one-parameter read tool 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 has 0% description coverage, so the description must compensate. It identifies request_id as the lookup key, but does not explain how to obtain it, expected format, or behavior for missing/expired IDs. The single string parameter is self-explanatory enough to remain usable, but not richly described.

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?

Starts with a specific verb and resource ('Read persisted delivery receipts by request_id') that immediately distinguishes it as a read/status operation from siblings like send_batch and batch_cleanup. It also lists what the receipts include, making the scope unmistakable.

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

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

The description establishes clear context for when to call it (query delivery status by request_id) and adds a practical rule: 'unconfirmed may mean delivered: do not retry automatically.' It does not explicitly name alternatives or exclusion conditions, so it falls just short of full 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 and destructiveHint=false, covering safety. The description adds value by explaining that roles/tags are metadata and never auto-added to client text, and that template contents fill text/paths by part id, plus custom part array support. This goes beyond annotations without contradicting them.

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 with no fluff. The main purpose is front-loaded, and subsequent details about metadata and template behavior are concise and relevant. Every sentence earns its place.

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

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

For a simple listing tool with one parameter and no output schema, the description covers the core return (list of templates and default), and explains key behavioral aspects. It doesn't mention pagination or exact response format, but given the simplicity, it's reasonably 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 0%, so the description must compensate. It clarifies that the sole parameter 'project' is the scope for listing, adding meaning beyond the schema's bare string type. It doesn't specify format (ID vs name) but gives enough context for a single required 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 states a specific verb ('List') and resource ('named batch templates and the default') scoped to a project. It distinguishes from siblings like send_batch/preview_batch by being a listing operation, and adds detail about metadata and template behavior, making 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 implies when to use it (when you need to list templates for a project) but provides no explicit guidance on when not to use it or alternatives like preview_batch or send_batch. Context is clear, but exclusions are absent, so it falls to 'implied usage'.

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, and destructiveHint=false, so the safety profile is covered. The description adds the intended timing ('before composing a message') but no additional behavioral traits such as authentication requirements, response format, or behavior when the optional project parameter is null. Since annotations cover the core read nature, a 3 is appropriate.

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, tightly worded sentence that communicates the tool's purpose and context with no wasted words. It is appropriately sized and front-loads the core function.

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

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

For a simple read tool, the description gives the essential purpose, but the sole parameter remains completely undocumented, which is a significant gap. With no output schema, the description also doesn't hint at what the response contains, though that is not strictly required. The missing parameter semantics makes the tool incomplete for an agent to use confidently.

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 description does not mention the 'project' parameter at all. The parameter is optional and may be self-explanatory to some degree, but with zero documentation in both schema and description, an agent has no guidance on what values are valid or how it affects the result. The description fails to compensate for the schema 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 states a specific verb ('Read'), a clear resource ('the current configurable writing style'), and a contextual trigger ('before composing a message'). It is immediately distinguishable from all sibling tools, which focus on sending, watching, and inbox operations, and there is no other tool that reads writing rules.

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 implies when to use this tool ('before composing a message'), which is a useful usage cue. However, it does not explicitly mention when not to use it or name alternative tools, though none exist among the siblings that serve a similar purpose. The condition is clear, but exclusions are absent.

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 says the tool 'deletes their downloaded copies,' which directly contradicts the annotation destructiveHint=false. This is an annotation contradiction, so the description cannot receive credit for behavioral transparency despite also disclosing TTL-based recoverability.

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 purpose and precondition, and every sentence adds substantive guidance. The buffer/disk explanation is slightly verbose but earns its place by explaining why deletion is safe.

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 no output schema, the description covers the prerequisite, the required parameters, opaque reference semantics, and recovery behavior. An agent has enough context to decide when and how to invoke 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 description coverage is 0%, so the description must carry the load. It defines each key as {chat_id: int, message_id: int} and requires a non-empty archive_ref identifying the recorded destination/batch. It could clarify the shape of the keys array itself, but the parameter semantics are meaningfully specified.

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 states a specific action ('Mark messages as archived') and its concrete effect ('deletes their downloaded copies'). It is clearly distinct from sibling inbox tools like inbox_fetch, inbox_status, and inbox_export.

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: call only after messages are in the archive with hashes, and explicitly says not to call if no archive_ref exists. It also warns that archive_ref is opaque and will not be parsed or called, so the agent knows not to treat it as a live reference.

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 only provide generic hints (readOnlyHint=false, destructiveHint=false). The description adds crucial behavioral context: it copies attachments, rewrites paths, marks messages as taken, and requires a fresh directory. It also discloses a failure mode (raw rows cause missing attachments). These are significant behavioral traits beyond what annotations convey, with no contradictions.

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, well-structured paragraph that front-loads the primary purpose and then efficiently covers usage, prerequisites, and exceptions. Every sentence contributes new information without redundancy. The length is appropriate for the complexity.

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 tool with 7 parameters, no output schema, and sparse annotations, the description covers the essential context: what it produces, when to use it, the state change it triggers, the required condition on target, and a specific follow-up. It does not describe the return value or format of the output folder, but since it's an action that writes a folder, that may be less critical. It also does not explain the 'range' parameters (since/until/chat) explicitly, but the name 'range' in the first sentence gives a hint. Overall, it is nearly complete for successful 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?

Schema description coverage is 0%, so the description must compensate. It explains 'target' (must be fresh directory) and 'include_taken' (rebuild for earlier messages). However, it does not clarify 'since', 'until', 'chat', 'limit', or 'scope' semantics beyond what their names and types suggest. It adds meaning to two key parameters but leaves the others to inference. Given the low coverage, this is a partial compensation.

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: 'Write a self-contained folder for a range, ready to import into an archive.' It clearly distinguishes from inbox_fetch by naming the alternative and the condition ('whenever the messages are going into the archive'). The purpose is explicit 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?

It explicitly recommends this tool over inbox_fetch for archiving, explains why (copies attachments, rewrites paths), warns about the failure mode of raw rows, and gives a follow-up action ('call inbox_done'). It also specifies prerequisites (fresh target directory) and the special case for include_taken. Clear when-to-use and 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?

Beyond the annotations, the description adds valuable behavioral detail: messages are marked as taken, fetching does not remove anything, forwarded messages preserve their real author, and include_taken reveals previously handed-out but unarchived messages. These details meaningfully inform an agent about side effects and data 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?

The description is organized into three focused paragraphs, each carrying essential information: core behavior, date and data semantics, and recovery workflow. Every sentence adds value, and the most important warning is front-loaded.

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 description covers the core workflow, non-destructive nature, date filtering, forwarded-origin behavior, and interrupted-batch recovery. The output schema exists, so return values need no explanation. The main gap is that some parameters (scope, chat, project, limit) are left to inference from names and defaults rather than being explicitly 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?

Schema description coverage is 0%, so the description must compensate. It explains since/until as ISO-8601 timestamps compared in UTC and explains include_taken, but it does not explain scope, chat, project, or limit. Those parameter names and the scope enum provide partial meaning, but the description leaves a real gap for the filtering 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?

The description opens with a specific verb and resource: 'Fetch buffered messages for reading and mark them as taken.' It clearly distinguishes itself from archive operations and names the archival siblings, so an agent can identify what this tool does and what it does not do.

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 this is not an archive operation, names the correct archival path (inbox_export, import, inbox_done), and explains when include_taken should be used for recovering interrupted batches. This gives clear when-to-use and 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 mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail beyond that: it does not fetch content, last_poll acts as a daemon heartbeat, and attention_required/taken_unarchived have specific operational meanings.

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 each sentence adds distinct operational guidance. It is compact despite carrying substantial warning and recovery context.

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 does a good job explaining the meaningful output fields (volume per chat, oldest age, last_poll, taken_unarchived, attention_required) and how to react to them. It loses a point because the three input parameters are left undocumented and the description does not clarify how scoping works.

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 for undocumented parameters. However, it never explains chat, scope, or project, leaving their effect on the summary ambiguous. The only parameter-related hint is 'volume per chat', which is not enough.

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 what the capture daemon has buffered' and explicitly distinguishes itself from inbox_fetch with 'without fetching content'. This clearly separates it from the sibling tool.

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 instructs the agent to 'Check this before inbox_fetch' and explains why: it reports volume and age so a fetch range can be chosen deliberately. It also gives conditional guidance for last_poll and attention_required, making when-to-use 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 idempotentHint=true, covering the safety profile. The description adds contextual detail ('allowed projects', 'default destinations') but does not disclose behavioral traits beyond that, such as ordering or filtering 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 a single, concise sentence that front-loads the action and subject. Every word adds value, with no redundant or filler content.

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 list tool with annotations covering safety and an output schema available, the description fully communicates the tool's purpose. The mention of 'allowed projects' and 'default Telegram destinations' gives sufficient context for 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 tool has zero parameters, so schema coverage is trivially 100%. No parameter descriptions are needed, and the description does not attempt to over-explain. The baseline for zero-parameter tools is 4, and nothing lowers it.

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 ('List') and resource ('allowed projects and their default Telegram destinations'), clearly distinguishing this tool from sibling send/inbox operations. It unambiguously states what the tool does.

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: call this to discover permitted destinations. However, it does not explicitly state when to use it over alternatives or provide exclusions, so 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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the useful scoping detail that messages are not read, but it does not describe output structure or other behavioral nuances; with annotations present, this is adequate but not exceptional.

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 that communicates purpose and scope with zero wasted words. The key distinction ('without reading messages') is placed at the end but remains immediately relevant.

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 with a full output schema and comprehensive annotations, the description is complete. An agent has everything it needs to select and invoke 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 tool has zero parameters, so the baseline is 4. The description correctly focuses on behavior rather than parameter details, and there is no schema information to compensate for.

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 resource ('capture sources') and adds the key detail 'project ownership', which distinguishes it from message-reading tools like inbox_fetch. It clearly identifies what the tool does and what it does not do.

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 'without reading messages' provides clear context that this tool is for source/ownership metadata, not message content. It implies when to use it but does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

The description adds useful behavioral context beyond annotations: it preserves the supplied summary, does not add a generic heading, appends a provenance signature, and defaults to HTML with raw Telegram tags. It does not contradict the annotations and elaborates on the actual transformation 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?

Three dense sentences front-load the purpose, then deliver a prerequisite, formatting behavior, and transformation guarantees. There is no 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?

The tool is complex with 10 parameters and two enums, and the description covers only a small subset of them. It provides good workflow context but is not complete enough for an agent to correctly populate the optional fields or understand the full sending semantics.

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. It provides some meaning for 'summary' (preserved as supplied), 'project' (used with get_writing_rules), and 'format' (HTML default), but leaves most parameters—agent, model, subject, preset, route, reply_to, reference—unexplained.

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 action ('send a completion notice') and a resource/context ('when the user requested notification'). It is clearly not a tautology and conveys the tool's distinct niche among siblings, though it does not explicitly name or contrast sibling 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?

It gives an explicit usage condition ('only when the user requested notification') and a clear prerequisite ('Call get_writing_rules(project) before composing the summary'). It does not discuss alternatives or exclusions relative to sibling send tools, but the stated condition provides meaningful selection guidance.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral details beyond that: no sending or storing, provenance is generated and requires reply_to, no automatic signatures are added, file paths and size limits are validated, and structural validation has specific limits.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose and non-mutating nature, then covers prerequisites, either/or input modes, part kinds, validation limitations, and reply_to semantics without repetition 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 complex tool with no output schema and no parameter descriptions, the description is remarkably complete on input semantics and behavioral caveats. The only noticeable omission is an explicit statement of what the preview/validation result contains, though the structure_only caveat partially addresses output interpretation.

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?

With schema description coverage at 0%, the description carries the burden of explaining parameters. It thoroughly explains the parts object, template/contents alternative, kinds, roles, tags, reply_to semantics, and top-level reply_part anchoring. However, required fields like project, subject, agent, model, and the optional route parameter are not explicitly explained.

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: 'Prepare and structurally validate a message batch without sending or storing it.' This clearly distinguishes the tool from send_batch and other sibling tools by emphasizing that it is a non-sending validation step.

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 explicit guidance: read get_writing_rules first, supply either parts or template/contents, and understand that validation=structure_only is not a claim of factual accuracy or client readiness. It also clarifies the separate meanings of top-level reply_to and a part's reply_to, so an agent knows how to use them.

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 richly discloses behavioral traits beyond the annotations: it explains reuse semantics (returns recorded receipts, rejects differing plans), error handling, album splitting into groups of ten, reply_to and reply_part semantics, internal/provenance part handling, and signature metadata. This goes far beyond the basic readOnlyHint, idempotentHint, and destructiveHint flags and gives an agent a clear mental model of what happens.

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 not wasteful; it packs multiple essential rules into a few sentences. It opens with the core action, then addresses idempotency, error handling, and part semantics in a logical order. It is appropriately sized for the complexity, though a reader must parse several compound sentences.

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 tool with 11 parameters and no output schema, the description covers many behavioral and edge-case aspects (idempotency, error handling, reply logic, album splitting). Yet it leaves some operational details vague, such as the exact format of 'recorded receipts' and how to interpret the returned state information, and a few parameters remain unexplained.

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?

With 0% schema coverage, the description compensates for the most confusing parameters: request_id (idempotency, reuse), reply_to and reply_part (hierarchical reply relationships), and album parts (file count limit and splitting). However, it does not explain other parameters like agent, model, project, subject, route, contents, and template, which an agent may need to understand to call the tool correctly.

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 action (send) and the resource (an explicitly authorized batch) and situates it in a workflow (after draft review and structural preview). It implies the batch nature distinguishes it from single-send siblings like send_text and send_files, but it does not explicitly name those alternatives or contrast them.

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 provides strong operational guidance: how to use request_id (reuse for receipts, don't create a new id blindly), how to handle errors (stop and report confirmed state), and the requirement to inspect part states. It implies it should be used after preview_batch, but does not explicitly state when NOT to use it or compare with single-send tools.

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 richly discloses behavior beyond annotations: it explains the 4096-character Telegram limit, the quote mode semantics, the rule that quotes must not hide required facts or reasoning, and the constraint to preserve all client-raised subjects. It also clarifies the question policy and the difference between brevity and omission. This substantially exceeds what the annotations alone convey.

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 first sentence front-loads the core purpose, and every subsequent sentence adds a distinct rule or constraint. It is long, but the tool is genuinely complex and the rules are dense rather than redundant. A more structured layout could improve scanability, but no sentence is wasted.

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

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

For a tool with 8 parameters, 0% schema coverage, and nested objects, the description covers the content-generation behavior thoroughly, including output limits and quote handling. It falls short on top-level metadata parameters and on explicitly contrasting with sibling send tools, but the output schema and the strong content rules make it largely sufficient 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?

Schema description coverage is 0%, so the description must compensate. It does explain the important nested content parameters well: topic titles must be concrete subjects, details hold facts/proposals/next actions, question is for the earliest unresolved blocker, and quote mode/title have specific meanings. However, it says nothing about the required top-level parameters project, subject, agent, model, route, reply_to, or reference, leaving the agent to infer their meaning from names 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?

The description opens with a specific verb and resource: 'Send copy-ready text addressed directly to the client.' It immediately distinguishes itself from generic send tools by tying use to 'explicitly requested named topics' and to producing manager-ready copy. The examples and exclusions make the tool's scope unmistakable.

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

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

The description gives a clear when-to-use condition: 'Use this tool for explicitly requested named topics, so a manager can copy the body without understanding the project or rewriting it.' It also gives explicit when-not rules for content, such as never using fixed report headings and omitting questions when no answer is needed. It does not name sibling tools like send_text or send_update as alternatives, so the differentiation 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?

The description adds meaningful behavior beyond the annotations: path must resolve under files.allowed_roots, kind=auto routes small images as Telegram photos and everything else as documents, and captions have HTML and 1024-character limits. It aligns with readOnlyHint=false and idempotentHint=false and does not imply destructive 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?

Four compact sentences front-load the primary action and then add only high-value constraints. There is no filler, repetition, or schema duplication.

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 tool with 11 parameters and no schema descriptions, the description leaves essential required metadata fields undefined and does not disambiguate from the sibling send_files. The output schema covers return shape, but invocation context remains incomplete, so an agent would struggle to fill project, subject, agent, and model 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?

With 0% schema description coverage, the description must compensate, and it does clarify path, kind, and caption semantics. However, six required parameters exist and several of them—project, subject, agent, model—are completely unexplained, along with route, reply_to, and reference, leaving most of the 11-parameter surface 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?

The description opens with a specific verb and resource: it sends an explicitly requested local file or image with a caption, so an agent can distinguish it from text-only senders like send_text. It does not, however, explicitly contrast it with send_files, send_update, or send_client_copy, so sibling differentiation is incomplete.

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 'explicitly requested' implies when this tool is appropriate, and the description gives useful operational context like files.allowed_roots and kind=auto behavior. However, it never states when to prefer send_file over send_files or send_update, nor does it give any explicit exclusions, so selection guidance is largely left to inference.

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

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

The annotations only indicate read/write, open-world, non-idempotent, and non-destructive behavior; the description adds substantial operational detail: album groups split into ten, mixed-media handling, caption/provenance carried once with later groups replying to the first, the 1024-visible-char limit, allowed_roots path restriction, and the explicit warning not to retry unconfirmed files. This greatly exceeds what annotations 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?

The description is dense but every sentence contributes a distinct behavioral or usage constraint. The core purpose and sibling alternative are front-loaded, and the rest consists of necessary boundary conditions rather than 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 complex 11-parameter tool with no output schema, the description supplies most operational context: size limits, mode semantics, media rules, provenance behavior, path restrictions, and retry policy. It is not fully complete because several parameter meanings are absent and the return shape is not described, though the status list 'complete, sent, unconfirmed, not_attempted' gives some expected outcomes.

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. It does clarify kind ('use kind=document for a mixed pack'), mode (album vs separate), caption (1024 visible characters), and paths (must be inside files.allowed_roots). However, required parameters agent, model, project, and subject, plus route, format, and reply_to, receive no semantic explanation, leaving clear gaps.

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 action: 'Send explicitly requested files as an album pack... or separate ordered messages,' including precise count ranges. It also distinguishes the tool from send_batch by naming exactly what send_batch is for, so an agent can tell them apart immediately.

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 an explicit when-to-use rule: 'Use this only for a simple signed pack; use send_batch when files need multiple captions, roles/tags, clean client copy or a separate provenance reply.' It also provides media-type guidance with 'use kind=document for a mixed pack,' making usage conditions 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?

With minimal annotations, the description carries the behavioral load and does so well: it discloses HTML as the default, requires raw Telegram tags rather than escaped HTML, notes the preset only controls editorial density, and imposes Telegram's 4096 visible-character limit. This goes meaningfully beyond what the schema or annotations 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?

The description is dense but not bloated; every sentence adds relevant information. It front-loads the purpose and then gives practical formatting rules. It could be slightly more scannable with bulleted formatting guidance, but the current structure is reasonable for the content.

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 a complex 10-parameter input schema with 0% schema description coverage and a large sibling family, the description is incomplete. It thoroughly covers Telegram formatting behavior but fails to explain the meaning or use of several required and optional parameters, and it does not route the agent away from overlapping send-related tools.

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 for 10 parameters, but it only adds meaningful semantics for preset ('editorial density') and project (via get_writing_rules). Parameters like subject, agent, model, route, reply_to, and reference remain unexplained, leaving the agent to guess their roles.

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 clear, specific action: 'Send a free-form formatted message with provenance metadata.' This is a strong verb+resource statement, but it does not explicitly distinguish send_text from siblings like send_batch, send_update, or send_client_copy, so it misses the full sibling-differentiation bar.

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 concrete usage guidance: call get_writing_rules(project) before composing, use raw Telegram tags, avoid HTML entities, and respect the 4096-character limit. However, it never says when to choose this tool over alternatives such as send_batch or send_update, so the when-vs-alternatives guidance is only implied, not explicit.

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 and destructiveHint=false, and the description does not contradict these. It adds meaningful behavioral context by disclosing that the server renders summary and nonempty list fields as escaped Telegram HTML, and that fields must respect preset-specific limits. This goes beyond what the annotations provide, though it doesn't discuss all potential side effects or error handling.

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—three sentences plus a prerequisite call—and front-loads the primary purpose. Each sentence adds value: purpose, prerequisite, rendering behavior/limits, and alternative. It is not verbose and avoids repetition, though it could benefit from slightly clearer separation of sections.

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 (14 parameters, 5 required) and the lack of schema descriptions, the description covers key operational aspects (prerequisite call, HTML rendering, limits, alternative) but omits details about individual parameters, expected outcomes, and error conditions. The presence of an output schema (though not shown) reduces the need to describe return values, but the description still leaves gaps in parameter semantics and edge cases.

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 for the lack of parameter documentation. However, the description only offers general guidance (e.g., 'summary and nonempty list fields' and 'preset-specific limits') without explaining individual parameters like project, subject, agent, model, route, preset, or reply_to. While parameter names are self-explanatory to some degree, the description does not provide the depth needed to fully understand each field's meaning or 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 clearly states the tool's purpose: 'Send an explicitly requested structured internal update.' It uses a specific verb (send) and a resource (structured internal update), and explicitly contrasts with send_text for free-form messages, distinguishing it from that sibling. This leaves no ambiguity about what the tool does.

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 guidance on prerequisites ('Call get_writing_rules(project) for the current writing style') and explicitly names an alternative tool ('Use send_text for free-form messages without those field limits'). It does not cover all sibling tools, but the primary distinction is made, which is sufficient for an agent to choose correctly.

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

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

Annotations already state this is not read-only audit, not idempotent-ey? Actually they state readOnlyHint=false and idempotentHint=false, destructiveHint=false, so an agent knows this is a mutating but not destructive operation. The description adds a basic behavioral outcome ('close' or 'record failure') but does not explain side effects, irreversibility, or what happens if the delivery is already acknowledged.

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 one efficient sentence that front-loads the primary outcome and then gives the failure alternative. There is no filler or redundant repetition of the tool name.

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 mutating tool with four parametersheb, no output schema, and minimal parameter documentation, the description is too thin. It omits what the return/response will be, whether an error string is required on failure, and what happens when acked delivery is repeatedly acked.

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 description does not compensate by explaining any parameters. Field names like duty_id and delivery_id are somewhat self-explanatory, but the relationship between success, error, and 'record failure' is never clarified, especially whether error is expected when success is false.

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 ('Close a claimed delivery') and adds a second mode ('record failure'), so an agent can see what the tool accomplishes. It also distinguishes itself from watch_reply by restricting use to cases where 'no content reply is required', though it does not explicitly name that 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?

The description gives clear conditions for use: close only when no content reply is needed, or record failure. It does not explicitly list when not to use the tool or point to alternatives such as watch_reply, but the distinction is implied strongly 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?

Annotations are minimal (readOnlyHint=false, destructiveHint=false), but the description adds crucial context: it's a self-report, stale activity is displayed as unknown rather than assumed busy, and only watch_wait updates last_poll_at. This goes beyond annotations to clarify the tool's non-authoritative nature and freshness 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 concise sentences, front-loaded with the core purpose and immediately followed by usage and behavioral clarifications. No filler or redundant phrasing; every sentence adds value.

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 the main operational aspects: what it reports, when to use it, and its limitations. However, it does not describe the duty_id parameter or its expected format, which is required. For a simple tool with only two parameters, this is a minor gap but one that an agent might need to resolve.

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. It lists the three possible values for the state parameter, matching the enum, but does not explain the duty_id parameter at all. While duty_id may be intuitive as a session identifier, the description leaves it undefined, which is a gap given the zero 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 clearly states the tool's function: 'Report this session's current activity' with explicit states (processing, waiting_user, idle). It distinguishes itself from siblings by noting that only watch_wait updates last_poll_at, positioning watch_activity as a self-reporting mechanism rather than a polling operation.

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?

Provides explicit when-to-use guidance: 'Use while working and after replying if waiting for input' and 'Refresh during long work when practical.' It also clarifies when not to rely on it: 'This is a self-report, not proof of polling' and 'Only watch_wait updates last_poll_at,' effectively routing the agent to the correct tool for polling updates.

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 readOnly/idempotent annotations, the description adds meaningful behavioral context: it 'never claims a delivery' and that 'all is refused unless watch.allow_inspect_all=true.' This helps the agent avoid unwanted side effects and understand the gated scope.

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 compact and front-loaded: the first sentence states the tool's purpose, followed by concise safety and routing notes. 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 output schema exists and annotations cover the read-only safety profile, the description provides the key contextual cues for correct use. It omits explicit duty_id/limit semantics, but those are partially inferable from names/defaults and do not create a critical gap for this inspection 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 0%, so the description must compensate. It clarifies the scope enum ('mine,' 'unaddressed,' gated 'all'), but does not explain duty_id or limit. Partial compensation is present, but not all parameters gain added 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 description uses a specific verb and resource: 'Explicitly inspect mine, unaddressed, or the gated all-delivery view.' It also clarifies that inspection 'never claims a delivery,' which differentiates it from state-changing sibling tools like watch_wait and watch_ack.

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 routes normal work to watch_wait instead and states the configuration condition that governs the 'all' scope (watch.allow_inspect_all=true). This gives clear when-to-use and 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds one behavioral trait beyond that: it explicitly clarifies that the operation does not register a duty session, which is a side-effect distinction not captured in annotations. That is useful extra context.

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

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

A single, tightly written sentence that front-loads the core action and then appends the one caveat. Every word earns its place, with no fluff or repetition of schema 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 parameterless, read-only, idempotent list operation with an output schema available, the description fully covers what an agent needs: it knows what it lists, that it has no side effects, and can rely on the output schema for return structure. 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 tool has zero parameters, so there is nothing for the description to explain. Per the rubric, a baseline of 4 applies when there are no parameters; the description appropriately stays silent on 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 ('List'), resource ('configured Watch profiles'), and adds a distinguishing clause ('without registering a duty session') that separates it from session-affecting siblings like watch_start or watch_reply. The agent can tell exactly what it does and how it differs from the rest of the Watch family.

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 'without registering a duty session' implies it is the safe, read-only way to view profiles, but it never explicitly says when to use it over alternatives or when not to. No sibling names or exclusions are mentioned, so guidance is 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.

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

The description adds meaningful behavioral detail beyond the annotations: Herald derives routing from duty_id, delivery_id, and the validated profile; it tries a native Telegram reply before falling back to a quoted reply only after explicit rejection; and the delivery closes only after a send receipt. This gives the agent useful expectations about execution order and side effects.

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 concise sentences with no filler. The first sentence states the core action, the second explains the derivation model, and the third covers execution and completion semantics. 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?

The description covers invocation context, routing derivation, fallback behavior, and completion semantics. Since there is no output schema, a note about the return value would improve completeness, but the description is otherwise sufficient 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?

With 0% schema description coverage, the description must compensate. It clarifies that duty_id and delivery_id drive Herald routing and that no Telegram/project/route/agent/model parameters are needed. However, it does not explain text, subject, or format beyond their self-evident names and the format enum/default.

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 action: replying to a claimed Watch delivery through its configured Herald route. It is specific about the verb and resource, though it does not explicitly distinguish itself from sibling watch_reply_batch or watch_ack.

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 context is clear: this tool is for replying to a claimed Watch delivery when duty_id and delivery_id are known. It does not provide explicit exclusions or compare against alternatives like watch_reply_batch, so while the usage context is evident, there is no direct 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?

The description directly contradicts the annotations: it calls the batch 'idempotent' and instructs reusing request_id for retries, while idempotentHint is false. It does add useful behavioral context about Herald deriving fields and checking delivery_state, but the contradiction is fatal per the rubric.

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 five sentences with the core purpose front-loaded. It contains no filler, and each sentence adds operational or usage value. It could be better structured with separators, but it is appropriately sized.

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 complex tool with 8 parameters, no output schema, and contradictory idempotency annotations. The description provides important warnings and derivation context, but it does not explain how to construct parts, what the response looks like, or what most parameters mean. An agent would struggle to invoke 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?

With 0% schema description coverage, the description must compensate. It gives meaningful semantics for request_id and delivery_id, and mentions parts generally, but leaves duty_id, subject, contents, template, and reply_part unexplained. This is insufficient for an 8-parameter tool.

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

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

The description states a specific verb and resource: 'Reply to a claimed Watch delivery with a named, idempotent batch.' It also distinguishes the tool from simpler siblings by listing its intended use cases: clean client copy plus separate provenance reply, multiple text parts, files, or albums.

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 when-to-use guidance ('Use this for clean client copy plus a separate provenance reply, multiple text parts, files or albums') and a strong when-not-to-do instruction ('never create another id to retry an unconfirmed delivery'). It does not explicitly name alternative tools, but the usage context 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 are minimal (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the description carries the burden. It discloses timing and side effects: 'Duties expire after 15 minutes'; 'replace is an explicit takeover; it is never inferred'; 'A background shell alone does not wake the AI'; 'Ending the turn still ends polling.' It also warns against a concrete failure mode (reporting unattended listening). No contradiction with annotations — registering is a mutation with care requirements, consistent with readOnlyHint=false and destructiveHint=false.

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?

At roughly 250 words this is long, but the length is justified by genuine operational complexity — delivery mechanics, expiry, and divergent platform behaviors. The structure is sound: purpose front-loaded, then the critical duty_id contract, then per-platform instructions, then expiry. It could be tightened (the two platform blocks are verbose), which keeps this at 4 rather than 5, but every sentence carries operational weight and the hierarchy (purpose before detail) is correct.

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 responsibly covers the return contract — it names both duty_id (required for reads/writes) and monitor_command (needed for completion), and explains the expiry lifecycle. It details the 'what next' for both platforms and the failure modes to avoid. Minor gaps: the semantics of the profiles list beyond the primary_profile note, and what 'Watch delivery' entails, are left implicit. For a complex 6-parameter tool with no output schema, this is strong but not exhaustive.

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. It explains the two genuinely non-obvious parameters: primary_profile ('Several profiles require an explicit primary_profile for #all replies') and replace ('an explicit takeover; it is never inferred'). The remaining params (agent, model, session, profiles) are left to context, but these are largely self-evident given the tool's stated purpose of registering an already-open session. It does not document every parameter but covers the high-risk ones, which is the right allocation given zero schema help.

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-resource pair ('Register this already-open AI session for deterministic Watch delivery') that states both action and scope. It sharply differentiates from siblings by declaring what it is not: 'This registers only. It does not start polling.' This immediately distinguishes watch_start from watch_wait, watch_stop, and watch_reply. Purpose 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?

Exceptional. The description explicitly routes usage by platform: Claude Code gets 'load it with ToolSearch("select:Monitor")... do not use Bash run_in_background', while Codex gets 'poll cooperatively with watch_wait(timeout=0)'. It gives negative guidance ('Never report unattended listening until a real addressed test reaches this session', 'do not report empty polls') and states prerequisites (verifying a host wake-up monitor). This is the strongest usage guidance dimension I have seen — an agent can act correctly with zero 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?

Goes far beyond annotations: it explains that registration is not polling, that monitor_alive does not prove AI wake-up, that stale activity is unknown, and that state=expired means the 15-minute lease ended and profiles were released. These are exactly the behavioral edge cases an agent needs to interpret status correctly.

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 long but front-loaded with the core purpose and each caveat adds useful semantic detail. No sentence is filler, though it could be tightened.

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 tool with no output schema, the description names the key returned fields and interprets lease_age_seconds and expired state. It could be more complete by describing the duty_id parameter and possible observed_state values, but the main usage context is covered.

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 0% and the only parameter, duty_id, is not described. 'This duty's' is only an implicit reference to the parameter; there is no mention of how to obtain a valid duty_id or what values are acceptable.

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?

Starts with 'Show this duty's delivery counts...' naming the verb, resource, and specific fields. This clearly identifies a per-duty status query and distinguishes it from sibling watch_* tools like watch_activity and watch_list.

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 'Use this to verify a promised listener,' which tells the agent the intended scenario. It also gives interpretive constraints (not polling, monitor_alive is only a probe) but does not name alternative tools or exclusion conditions.

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 only communicate that the operation is not read-only and not idempotent. The description adds specific behavioral detail beyond those flags: it stops the duty and moves unfinished deliveries back to their profiles. This is consistent with the annotations and gives the agent a concrete expectation of side effects.

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 sentence that front-loads the primary action and immediately states the resulting behavior. It contains no filler, no repetition of the tool name, and no redundant schema 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 low-complexity tool with one required parameter and no output schema, the description conveys the core semantics: what action is performed and what happens to unfinished deliveries. It omits minor details like how to obtain the duty_id or what happens after stopping, but the simplicity of the tool makes this acceptable.

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 description does not mention the duty_id parameter at all. The parameter name is self-descriptive, but the description provides no additional information about where duty_id comes from, its format, or how it relates to the stated 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 starts with a specific verb, 'stop,' identifies the resource as 'this duty,' and adds the concrete consequence of returning unfinished deliveries to their profiles. This clearly distinguishes it from the other watch_* sibling tools, none of which describe stopping.

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 'this duty' implies an active duty exists and that this tool ends it, which is useful context. However, the description does not explicitly say when to use this tool versus alternatives like watch_start, watch_ack, or watch_status, so the usage context must be inferred.

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 adds behavior beyond annotations: it waits (blocking), claims a delivery, and returns a null delivery on timeout. It also discloses scoping constraints. Annotations already indicate non-read-only behavior, so the description does not need to restate that, and it does not contradict them.

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 with the core action. Every sentence adds necessary information: what it does, what it never does, and what happens on timeout.

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 description covers primary behavior and timeout output, which is useful given there is no output schema. However, it does not describe the success return shape or any prerequisites or lifecycle relationship with tools like watch_start. For a blocking claim operation, an agent would benefit from knowing what a successful response contains.

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?

With 0% schema description coverage, the description must compensate. It explains duty_id as the delivery's addressing target, and timeout is implied by 'A timeout returns...' rather than being explicitly tied to the timeout parameter with units or default behavior. The schema supplies the default, but the description leaves part of the timeout semantics implicit.

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: 'Wait for and claim only the next delivery addressed to this duty_id.' It also clearly scopes the operation by stating what it never returns, distinguishing it from queue-wide or cross-session 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?

The description gives clear context for when to use the tool: it is for claiming the next duty-specific delivery and waiting for it. It also communicates exclusions—never another session's delivery, unaddressed messages, or a global queue—which helps an agent avoid choosing it for those cases, though it does not name sibling alternatives explicitly.

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