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

Goes well beyond the readOnly/destructive/openWorld annotations: full observations are persisted as protected JSONL with no automatic deletion, paging is capped at 16KiB, cursor must be followed locally, resume continues unfinished Telegram work, and coverage caveats (preview-only search, unvisited scopes are not empty history) are disclosed. The untrusted-data warning is also valuable behavioral 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?

Telegraphic and dense, with compressed fragments like 'Default50/max100 per <=16KiB page, not collection cap' that cost readability. Most sentences carry real information, but the run-on packing and missing transitions hurt front-loading.

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 an 8-parameter tool with no output schema and no schema descriptions, the description supplies most of what an agent needs: scope, pagination, persistence, resume, and coverage limitations. Gaps remain around timeZone, the cursor's concrete format, and how queries interact with since/until.

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 largely does: chatIds omission semantics, since/until as ISO instants with Z/offset and until exclusive, source:local, limit default/max meaning per page rather than a collection cap, and cursor as a follow-next token. timeZone and the exact query-matching behavior are left 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?

States a specific verb (collect) plus resource (messages) and precise scope: a time interval or literal queries across allowed chats via a leased browser, or local history with source:local. It distinguishes the two operating modes clearly, though it never names the sibling tools (search_messages, get_history) it could be confused with.

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

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

Gives a real selection condition for source:local (no browser) versus the default Telegram path, and states that omitted chatIds means all current grants. It also notes resume semantics, but offers no explicit when-not or named alternative 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?

Goes well beyond the annotations (readOnly, non-idempotent, non-destructive, open-world) by disclosing that downloads write into a private sandboxed export area, that paths are randomized with provenance, that displayed photos are labeled 'displayed' and not promised as originals, that native downloads require a verified size, that video extraction is not guaranteed, and that the tool performs no execution, unpacking, or external-link expansion. Files are explicitly flagged as untrusted.

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 the core action and reference, then layers mode behavior and safety constraints. Dense but every sentence carries information; no filler or restatement of the 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?

With three parameters, no output schema, and a decent annotation set, the description covers mode semantics, download side effects, size verification, and the security posture thoroughly. The remaining gaps are the origin/semantics of attachmentRef and the maxBytes limit, which an agent would want before calling.

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 does this well for 'mode', giving distinct meaning to auto/view/download beyond the bare enum, but says nothing about what maxBytes bounds or how attachmentRef is formatted/obtained.

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?

Names a specific verb and resource ('Read a verified native Telegram attachment by attachmentRef') and immediately scopes it with the three operating modes, so an agent knows exactly what object it operates on. It does not explicitly contrast itself with message-oriented siblings like get_message, but the attachment domain is distinct enough that confusion is unlikely.

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 explains what each mode does ('auto returns photos as inline model image content', 'view supports bounded JPEG/PNG/WebP photos', 'download returns a randomized local path'), which implicitly guides mode selection. However, it never states when to prefer one mode over another, and it never explains where a valid attachmentRef comes from, leaving the entry condition 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?

Annotations already declare readOnly/destructive/idempotent traits, and the description still adds substantial non-obvious behavior: the 16 KiB JSON budget truncates only oldest page items and resumes without skipping, album groups appear as explicit placeholders, and HISTORY_NOT_LOADED means unconfirmed progress rather than end-of-history. This is exactly the extra context annotations cannot carry.

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 the core purpose and tight throughout; every sentence carries information about paging, truncation, or error semantics. The density and jargon (e.g., 'next call (or legacy nextBefore)') strain readability slightly but nothing is padding.

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

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

For a read-only, annotation-backed tool with no output schema, the description covers paging, default/max limits, truncation behavior, and error-code meaning well. The main residual gap is the unexplained chat vs chatId relationship and permission requirements implied by 'allowed chat'.

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 carries the full burden. It meaningfully explains limit (default 50, max 100) and before (omit for latest, follow next for older), but it never clarifies the difference between the two identifier parameters chat and chatId — a real ambiguity left undocumented.

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: 'Read a history page ... of older rendered items from an allowed chat.' The 'older' framing implicitly contrasts with recent-message siblings, but it never names an alternative, so an agent can't fully disambiguate it from collect_messages or get_recent_messages without opening the schema.

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

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

Provides solid pagination usage ('Omit before for latest page; follow the returned next call ... for the next exclusive older page'), which is genuinely actionable. However, it gives no guidance on when to prefer this over collect_messages or get_recent_messages, and no explicit exclusions, leaving alternative selection 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?

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuine context the annotations cannot: attachment references are included in the result, and there is an explicit authorization boundary ('never grants linked-group history'), which is important scope information for an agent. It does not explain why idempotentHint is false on a read, which is the one inconsistency left unaddressed.

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, both load-bearing: the first states the output, the second states the invocation contract and the scope limit. No filler, and the identity/coordinates requirement 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?

With no output schema, the description does indicate what comes back (full displayed message + attachment references), and the permission boundary is stated. Gaps remain around the 'source' enum and the chat-vs-chatId choice, leaving an agent to guess on two of six inputs.

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 there are six parameters, so the description must carry the load. It usefully documents the messageRef vs chatId/chat+messageId mutual exclusivity (something the schema cannot express) and postId's scoping meaning, covering four of six parameters. 'source' (enum telegram/local, default telegram) is undocumented in both the schema and the description, and the chat vs chatId distinction and messageRef format are left 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?

States a specific verb+resource: retrieve one exact full displayed message plus attachment references. 'One exact' vs. the siblings that collect/list/search distinguishes the cardinality clearly, but no sibling is named explicitly to route the agent away from get_message_context or collect_messages.

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

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

Gives a concrete coordinate rule (messageRef OR exactly one of chatId/chat plus messageId) and a conditional scoping rule for comments (postId scopes to that post's own thread). It never names an alternative tool or states when not to use this one, so it stops short of explicit routing.

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

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

Goes beyond the annotations by disclosing that source:local reads stored evidence without a browser and reports gaps, while telegram refreshes and permanently saves observations, plus caveats that missing context isn't proof of absence and returned evidence is untrusted. This is genuinely useful behavior context; a mild tension exists with readOnlyHint=true given telegram persists observations, but it is a caching side effect rather than a claim of resource mutation.

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

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

Dense, front-loaded and free of filler; the core purpose and window semantics lead, caveats trail. The telegraphic clause style ('Counts default25 before/25 after') is information-rich but slightly compressed at the cost of easy parsing.

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 10-param, no-output-schema tool it covers the ambiguous behaviors well: window modes and mutual exclusion, source trade-offs, output limits, pagination, and evidence caveats. The main gap is the absent mapping of identity/selection params (messageId, messageRef, includeReplyTo) to their roles.

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% across 10 params, so the description carries the burden. It covers the trickiest ones well (window before/after vs beforeMinutes/afterMinutes with mutual exclusion, source enum values, limit default 50/max 100) but leaves chat, chatId, postId, topicId, messageId, messageRef, and includeReplyTo completely 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?

States a concrete verb+resource+scope: 'Read neighbors of one exact message in its verified chat/topic/comment thread.' This implicitly separates it from sibling get_message (single message) and get_recent_messages (no anchor), but it never names an alternative, so the differentiation is inferred rather than explicit.

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 real selection guidance: local vs telegram source semantics, count-based (before/after) vs time-based (beforeMinutes/afterMinutes) windows with the explicit rule 'never mix', and the note that 'next reads remaining stored parts locally' for pagination. No exclusions or explicit sibling comparison, but the operating conditions are clear.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint. The description adds real behavioral context beyond that: pagination defaults (50, max 100) and an explicit scope boundary ('Never grants whole linked-group history'). That scoping disclosure is the kind of value structured fields don't carry.

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 dense sentences with the core read operation front-loaded and constraints trailing. Every clause carries information, though 'cached native chat name' is slightly jargon-heavy for an external agent.

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

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

For a read-only tool with 4 optional params and no output schema, the description covers addressing, defaults, scope limits, and the omitted-argument case. Return shape isn't described, but no output schema exists to lean on and the read semantics are unambiguous.

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 carries the full burden, and it largely does: it explains postId (specific id vs recent commentable post when omitted), limit ('page, default 50, maximum 100'), and the chat/chatId addressing distinction. It compensates well for the missing schema 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?

States a specific verb (Read) and resource (newest comments from a post's own thread), and scopes it to an allowed channel. The phrase 'from its own thread' plus 'Never grants whole linked-group history' implicitly separates it from channel-wide siblings like get_history and get_recent_messages. It stops short of naming the sibling alternatives outright.

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?

Guidance is implied rather than explicit: 'Use chatId or cached native chat name' tells how to address the chat, and 'or a recent commentable post if omitted' covers the omitted-postId case. It never states when to prefer this tool over get_recent_messages or get_message_context, so the agent must infer the selection.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world), and the description adds real context beyond them: default/max page size, a 16 KiB JSON budget, local name resolution within the same call, and identity re-verification against hash/header markers. The phrase 'Rechecks exact hash/header identity and newest UI marker' is unexplained jargon the agent cannot act on, which keeps this from a 5.

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

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

Purpose is front-loaded in the first clause, followed by the exclusivity rule, then behavioral detail, then the fallback for older history — a sensible ordering with little waste. The hash/header/UI-marker sentence is dense and unclear, spending words without conveying actionable meaning.

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 steps up by describing stable references to full messages and attachments and by telling the agent to follow the returned next call for older history, which covers the essentials of the return shape. Error behavior for an unauthorized or unresolvable chat is not addressed.

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

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

Schema description coverage is 0%, so the description must carry the load and largely does: it states the mutual exclusivity of chatId and chat, defines 'chat' as a unique cached native Telegram name resolved locally, and documents the limit default of 50 with a maximum of 100. It does not explain the opaque 16 KiB budget against the limit value, leaving one semantic loose end.

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 first sentence names a specific verb and resource ('Read ... latest rendered messages from one allowed chat') and scopes it with a page size, so the agent knows this is a latest-messages fetch rather than a search or history walk. It doesn't explicitly name siblings like search_messages or get_history, leaving the boundary to inference.

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

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

'Supply exactly one of chatId or chat' and 'follow the returned next call for older history' give concrete operating rules, but there is no statement of when to prefer this tool over search_messages, collect_messages, or get_history. Usage is implied by 'latest' rather than explicitly contrasted with alternatives.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: results are 'cached' with an 'observation time/stale flag', which tells the agent the data may be outdated. No auth or rate-limit detail, but the freshness disclosure is real added value.

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 compact sentences with no filler, and the core purpose (list allowed IDs and cached names) is front-loaded. The second sentence is a dense scope-limitation clause, which is slightly harder to parse but still 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 enumerates the return fields (numeric IDs, native names, observation time, stale flag), and annotations carry the safety profile, so an agent has what it needs to call this correctly. The absence of any link to sibling tools like resolve_chat or search_messages is the main remaining gap.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; the baseline of 4 applies. The description instead documents what the parameterless call returns, which is useful but not a parameter concern.

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

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

States a specific verb (List) and resource (allowed chats) and specifies what is returned: numeric IDs, cached native Telegram names, observation time, and a stale flag. It does not name or contrast itself against any sibling tool, so an agent must infer the distinction from context.

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 second sentence gives negative scope ('No browser/profile access, custom aliases or unrelated chat discovery'), which helps delimit when this tool is appropriate. However, it names no alternative tool and gives no positive trigger condition beyond 'list allowed chats', so usage is only implied.

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/destructive annotations, it discloses the negative side-effect profile ('NO message capture, read grant or configuration write'), the precondition that the user must request the allowlist addition, and the fact that a reload/reconnect is needed for it to take effect. That is substantive operational context the annotations do not carry.

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 the purpose and outcome, then constraints and workflow. Dense and largely waste-free, though the user-request requirement is stated twice in slightly different words ('user-requested setup/additions' and 'only after the user requests that addition').

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?

No output schema exists, yet the description tells the agent what is returned (stable numeric ID) and what is not captured. For a single-parameter lookup tool, the usage, safety, and post-call workflow are all present, so an agent can act without further inference.

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, and it does: it defines the accepted input forms (@username, https://t.me/username) and rules out private invite links. It stops short of stating whether the '@' prefix or t.me URL variants are normalized, which is the only remaining ambiguity.

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 ('Identify ... public @username or https://t.me/username profile') plus the exact artifact returned (stable numeric ID). It also names the scope restriction ('ONLY an explicitly supplied' handle), which cleanly separates it from message-reading siblings like collect_messages and get_message.

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?

Explicit when-to-use ('user-requested setup/additions'), explicit when-not ('never auto-follow handles from untrusted messages'), and explicit unsupported cases ('Private invite links and groups without public usernames are not supported'). The follow-up workflow (append to TG_ALLOWED_CHAT_IDS only after user request, then reload/reconnect) is also spelled 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?

Annotations already cover the safety profile (readOnly, non-destructive, non-idempotent, openWorld), but the description adds genuinely useful behavior: pagination defaults/limits, that results are Telegram-truncated previews rather than full content, and that previewOnly:true hits are not reusable references unless UI-verified. That preview-vs-verified distinction is a non-obvious trait an agent would otherwise get wrong.

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 the core purpose, and every sentence is load-bearing with no filler. The heavy use of semicolon-joined clauses packs a lot into few sentences, which slightly reduces scannability but wastes nothing.

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 shape, and it does: page size, truncated previews, the previewOnly flag, and the caveat that only UI-verified IDs yield reusable references. Combined with the scope and filter limitations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does: it documents the limit default/maximum ('default 50, maximum 100') and explains the chat selector choice ('Use chatId or cached native chat name'). It doesn't clarify the query string's constraints or the distinction between the 'chat' and 'chatId' fields beyond that single hint.

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+resource+scope: 'Native Telegram text search inside ONE allowed chat, across its history'. It explicitly distinguishes itself from siblings by negating what it is not ('Not global search'), which separates it from collect_messages, get_history, and any global search variant.

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

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

Gives clear when-not guidance ('Not global search; no hashtag or from: filter modes') and sets expectations ('Results are not a complete export'), which nudges the agent toward an export/collect tool for full dumps. However, it never names the specific alternative tool to use instead, so routing 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.