PostEveryPlatform

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds what the returned document contains (choice lists sourced from the network, not_available reasons, per-format media rules) but does not disclose cost, latency, or freshness of the network reads, which matters for a tool whose output changes as boards/pages/playlists change.

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 run-on sentence packing a dozen concepts and nested parentheticals, followed by terse fragments ("lists.<name>.field says where each choice goes"). The most actionable instruction – read options_schema before setting per-platform options – is buried at the very end rather than 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 must describe the return shape, and it does enumerate the top-level keys (lists, not_available, options_schema). However the enumeration is impressionistic rather than structural, leaving the agent to infer the overall document layout for a fairly complex payload.

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

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

Schema coverage is 100%, so the baseline applies. The description does add real meaning beyond the schema by explaining that supplying `subreddit` yields that subreddit's flairs and its flair rule, and that `account_id` scopes the returned schema to options.targets[<this account id>]. That is useful, but it is folded into a dense clause rather than stated plainly.

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 identifies the resource: the per-account posting rules and option choices (text limits, formats, required fields, choice lists, not_available, options_schema). It omits an explicit verb ("Returns" / "Get") and reads as a payload enumeration rather than a crisp verb+resource statement, but the substance is unambiguous and is clearly distinct from the analytics/listing siblings.

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

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

Closes with explicit usage direction: "Read it before you set per-platform options" for create_post's options.targets[<account id>], which tells the agent exactly when this tool is the prerequisite. It does not name an alternative or exclusion, but the sibling set (analytics, listings, scheduling) has no real overlap, so the guidance is sufficient in context.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation, so the description has a lower burden. It adds useful behavioral context by naming the exact metrics returned, defining engagements as likes plus comments plus shares, and specifying per-platform numbers and top 5 posts by views.

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 front-loaded sentence that first establishes the scope and then lists the returned metrics. There is no filler, and every listed item appears relevant to an agent deciding whether to call the tool.

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 carries the burden of explaining return values, and it does list the main metrics, per-platform breakdown, and top 5 posts. It could be more complete about the response structure, but it provides enough for an agent to understand the tool’s output.

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

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

Schema coverage is 100%, and the single parameter already documents its 7–90 range and default value. The description reinforces that days means the last N days, which adds a little semantic clarity, but it does not provide meaningfully richer details beyond the schema.

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

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

The description clearly states that the tool returns aggregate totals for a lookback window, and it enumerates the specific metrics returned. It does not explicitly distinguish itself from related siblings such as get_post_analytics, so it falls short of the top score for sibling differentiation.

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 by saying it returns totals for the last N days, which suggests an aggregate analytics-summary use case. However, it gives no explicit when-to-use guidance, no exclusions, and does not point to alternatives like get_post_analytics or get_best_times.

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: the 90-day aggregation window, workspace-timezone slotting, the 10-published-post data threshold, and the graceful 'it says so' fallback when data is insufficient. It does not say whether results are sorted or how many slots are returned.

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 dense sentence that front-loads what is returned before the precondition. Nothing is wasted, though the clause about the 10-post minimum is tacked on and could be separated for readability.

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

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

With no output schema, the description carries the return-value burden and does it well: it describes the shape (weekday + hour slots), the metric, the timezone, and the insufficient-data message. Only the ordering/length of the returned slot list is left unspecified.

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

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

Schema coverage is 100% and the single param is documented, so the baseline is 3; the description earns above that by explaining the omission semantics — without a platform you get overall results, with one you get per-platform results. That is genuine meaning beyond the schema's 'Only this platform'.

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 pair (returns weekday + hour slots ranked by average engagement) with the exact metric (likes + comments + shares) and time window (last 90 days). An agent knows precisely what it gets back. It does not distinguish itself from the adjacent sibling get_next_slots, which is the main clarity gap.

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

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

Usage is implied rather than stated: the 90-day lookback and 'overall and per platform' framing suggest planning/best-time analysis, and the 10-post precondition tells the agent when the tool is meaningful. But there is no explicit when-to-use clause and no routing to alternatives such as get_next_slots or get_analytics.

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 fully covered. The description adds the useful behavioral detail that results are unshortened full text, but says nothing about error behavior for a missing id or the response shape.

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?

One sentence, front-loaded with the identity ('one idea card by id') and immediately followed by the differentiating fact. Nothing 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 one-param read tool with full schema coverage and no output schema, the description is nearly sufficient: identity, selection criteria, and the full-text nuance. Only the return structure/failure mode remains unstated, which is acceptable here.

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 a single parameter at 100% schema description coverage ('Idea id from list_ideas'), the schema does the work. The description only echoes the id-based lookup, adding no format or provenance detail beyond the schema.

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

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

States a specific verb and resource ('One idea card by id') plus the key differentiator from the sibling: this returns full text while list_ideas shortens long ones. An agent can distinguish it from list_ideas without opening either 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?

The parenthetical naming list_ideas as the source of ids and the truncating alternative gives clear context for when to pick this tool. It stops short of an explicit 'use this when you need full body text, not for discovery' exclusion, so a 4 rather than 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?

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds meaningful behavioral detail beyond annotations: results are per-link and per-platform, and robot previews are counted as previews rather than clicks.

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 tightly written sentences with no redundant material. The short-link precondition is front-loaded, and the preview-vs-click clarification is included only because it affects interpretation of the metric.

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-only analytics retrieval with one parameter and no output schema, the description supplies enough conceptual detail to call and interpret it correctly. It does not describe the exact response shape beyond the conceptual dimensions, but the core semantics are present.

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

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

Schema description coverage is 100% and there is only one parameter, post_id, already documented as 'Post id'. The description adds contextual meaning by indicating the post must have short links enabled, but it does not add further post_id formatting or retrieval semantics.

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 a specific resource: clicks on each short link, per platform, for a given post. It implies the short-link-specific scope but does not explicitly contrast itself with sibling analytics tools such as get_post_analytics or get_analytics.

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 applicability condition: the post must have been sent with short links enabled via options.shorten. It also clarifies that previews are not clicks, which is useful context. It does not name an alternative tool for posts without short links.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavior: results are ordered soonest-first and expressed in the workspace timezone, and the first slot is the one consumed by queue-mode posting.

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, zero waste, with the core definition front-loaded and the usage hint second. Every clause carries information the agent needs.

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, and the description compensates reasonably by specifying ordering and timezone, but it never says the return is a list of datetime strings or what format they take. It also omits the count cap of 10, which an agent could otherwise only learn from the schema.

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

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

Schema coverage is 100% and the single 'count' parameter is documented there with a default and 1–10 bounds. The description says nothing about count, so it adds no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource: returns the next free times in the workspace's posting queue, soonest first, in the workspace timezone. That is clearly distinct from list_posts or get_schedule, though it never explicitly separates itself from the adjacent get_best_times, which an agent could easily confuse with it.

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 concrete downstream instructions: pass a returned slot as scheduled_at, or let create_post with when="queue" take the first one automatically. It stops short of exclusions — it never says when to prefer get_best_times or get_schedule instead.

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 non-destructive behavior, so the safety profile is covered. The description adds useful return-shape context unavailable elsewhere, notably that each account entry carries either the live link or the per-account error, and that the owner's note appears only if sent back.

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 names the resource, the key input, and the returned fields with zero filler. Every clause contributes information an agent cannot get from annotations alone.

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 carries the burden of explaining return values and does so by enumerating fields and the conditional per-account error/note behavior. For a one-parameter read-only getter with full schema coverage and rich annotations, this is nearly complete; exact field formats or absence cases are not spelled out.

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

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

Schema description coverage is 100%, and the schema already explains that the id comes from list_posts or create_post. The description repeats only 'by id' and adds no format or example detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific operation: retrieve a single post by id, and enumerates the content it returns (text, status, time, accounts, media, first comment, owner's note). This distinguishes it from list_posts and get_post_analytics by implication, though no sibling is named explicitly.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as list_posts or preview_post; the only routing hint, that the id comes from list_posts or create_post, lives in the schema rather than the description. Usage is only implied by the singular scope.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description need not repeat safety details. The description adds valuable behavioral context: the exact metrics, engagement-rate definition, newest-first ordering, and per-platform grouping.

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 tight sentences, front-loaded with the metrics and scope, then the single-post filter. Every phrase contributes useful information: metrics, engagement-rate meaning, grouping, time range, ordering, and post_id usage.

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-only analytics query with full schema coverage, complete annotations, and no output schema, the description is complete enough. It lists the returned metrics, engagement-rate definition, grouping, ordering, and filtering behavior, leaving no major ambiguity 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 100%, so the schema already documents days, limit, and post_id. The description adds a little meaning by noting the 1-to-365 day range and explaining that post_id limits results to one post, but it does not add information about limit or pagination beyond the schema.

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

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

The description clearly states the specific metrics returned (views, likes, comments, shares, engagement rate), the grouping unit (each published post and platform), the time window, ordering, and the single-post filter. An agent can distinguish this per-post analytics tool from broader account analytics 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?

It gives useful usage context: the last N days range and passing post_id for a single post. However, it does not explicitly compare this tool with siblings such as get_analytics, get_best_times, or get_link_clicks, so the agent must infer when to choose this per-post metrics view over 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 readOnly/idempotent/non-destructive, so the description correctly focuses on semantics rather than safety. It adds real context the annotations cannot: day indexing convention (0 = Monday), the HH:MM format, the workspace timezone, and that state is owner-managed elsewhere.

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 dense sentence front-loads the return contents and appends the formatting conventions and ownership note. Every clause carries information; it loses a point only for packing four distinct facts into one run-on sentence rather than structuring them.

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 must carry return semantics, and it does: it enumerates the response fields conceptually and explains the time encodings. A minor gap is that it does not name actual field keys or indicate ordering of the weekly times.

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 the baseline is 4. The description productively uses the space to define the encoding of the values it returns rather than restating nonexistent inputs.

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 resource and enumerates what the read returns (weekly posting times, paused flag, queue depth, next free slots), so the agent knows exactly what it gets. It does not, however, distinguish itself from siblings like get_next_slots or get_best_times, which cover overlapping time-related ground.

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

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

Usage is only implied: the closing note that 'the owner changes the schedule in the app' signals this is a read-only source of truth for the current configuration. There is no explicit when-to-use or when-to-prefer-get_next_slots guidance, which matters given the closely related siblings.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile. The description adds useful context beyond that by listing the returned fields and stating the cross-tool timezone convention, though it does not discuss error or permission-failure 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?

It is front-loaded with "Start here" and then gives a compact enumeration of the returned information. The timezone note is short and directly relevant, with no wasted 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?

With no output schema, the description does a good job covering the main return values and the important timezone convention for other tools. It could be slightly more complete by mentioning exact field names, workspace identifiers, or return structure, but it is sufficient for an agent to call a zero-parameter read 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?

The tool takes no parameters, so there is no parameter semantics to explain. The description appropriately focuses on what the call returns rather than on nonexistent inputs.

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 identifies the workspace context resource and enumerates exactly what it returns: workspace name, timezone, plan limits, monthly post usage, approval requirement, and permissions. No sibling tool covers this workspace-level scope, so an agent can distinguish it 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?

"Start here" gives clear initial-call guidance, and the timezone note tells the agent how to interpret times in other tools. It does not specify when not to use it or name alternatives, but no sibling appears to overlap this purpose.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds real value beyond them by disclosing the status field semantics and the 'disconnected' constraint, though it says nothing about ordering or result size.

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 tight sentences: field list first, then the actionable constraint. Nothing is repeated from the title or annotations and nothing 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?

No output schema exists, so the description correctly supplies the return-field list, and for a zero-parameter read tool that is all an agent needs to call it and interpret the result.

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 and the schema is fully described, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter discussion is needed or expected.

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?

Specific verb+resource ('The social accounts connected to this workspace') plus an enumeration of the returned fields, which lets an agent decide instantly whether it needs this data. It does not explicitly contrast itself with any sibling tool, so it stops short of a 5.

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 concrete downstream usage ('Use the ids in create_post') and a precondition warning that 'disconnected' accounts can't post — genuinely actionable context. It stops short of explicit when/when-not framing or naming an alternative tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met; the description adds substantive behavior the annotations do not: a 14-day recency window, 40-item pages, newest-first ordering, and per-item capability flags (can_reply / can_like / can_hide) that signal platform-varying affordances. It does not state what happens when the window is exhausted, which keeps it 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?

Three short sentences with the result-set scope, the filter vocabulary, and the pagination rule front-loaded in that order; nothing is padded. The telegraphic sentence fragments ('can_reply / can_like / can_hide say what each platform allows') trade a little readability for density.

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

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

With no output schema and no required parameters, the description carries the return-shape burden and does so by naming the item-level capability flags, page size, ordering, and the pagination cursor. It is nearly complete; the only omission is any guidance on account_id scoping or what an empty result implies.

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

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

Schema coverage is 100%, giving a baseline of 3, and the description earns above that by defining the non-obvious filter values and by explaining that the previous response's 'next' token is passed as 'before'. The account_id parameter is not addressed at all in the description, which is the remaining 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?

Names a specific verb+resource ('list comments') and narrows scope precisely: comments on this workspace's posts from the last 14 days, newest first, 40 per page. That is far more than a restatement of the title. It falls short of a 5 because it never contrasts itself with the very similar sibling list_review_comments, so an agent must guess which list to call.

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?

Explains what each filter value means ('needs_reply (not answered yet)') and how to paginate ('Pass next back as before for older ones'), which is genuine invocation guidance. However, there is no statement of when to prefer this over list_review_comments, list_notifications, or list_feed_items, and no exclusions or preconditions.

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=false, so the description adds genuine context beyond them: it enumerates the returned fields and clarifies that feed subscriptions are managed by the owner in the app, so this endpoint cannot add feeds. It omits ordering and pagination behavior, which is the main remaining gap.

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 the resource front-loaded and the usage hint second. The first sentence mildly conflates 'the feeds followed' with 'the items they brought', 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 single-parameter read-only list tool with no output schema, the description covers what is returned (fields), where it comes from, and that feed management is out of band. An agent has enough to call it correctly without further context.

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

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

Only one optional parameter (limit, default 20) and schema description coverage is 100%, so the schema carries the load. The description adds nothing about limit, result ordering, or whether the newest items come first, so baseline 3 applies.

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

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

The description states the specific resource (RSS/Atom feed items from followed feeds, surfaced on the ideas board) and enumerates returned fields (title, summary, link). It is clear what the tool returns, though the verb is implicit and the overlap with sibling list_ideas is not addressed.

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?

'Good material for posts: summarise or comment on an item and link to it' implies a use case (content inspiration) but gives no when-not conditions and never names an alternative among list_ideas, get_idea, or search_mentions. Usage is inferred rather than stated.

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 fully covered without the description. The description adds useful structural context (three-column status model, RSS-sourced items) but says nothing about ordering, the default page size, or what a result row looks like.

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 short sentences, front-loaded with what the board is, then search, then the follow-on workflow. Minor ambiguity: 'post ideas in three columns' can momentarily read as the verb 'post' rather than 'ideas are posted here'.

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 must carry the burden of describing results; it conveys the board/column model and RSS inclusion but not pagination, ordering, or the shape of a returned idea. Adequate to call correctly, but thin for an untyped list response.

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

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

At 67% schema coverage, q and limit are already documented in the schema, and the description's 'Search with q' adds nothing beyond it. The three column names do give meaning to the otherwise undescribed status enum, but that is a single contribution against a partially covered 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 identifies the resource concretely: an ideas board with three columns (idea, drafting, ready) that also holds items imported from RSS feeds. That distinguishes it from get_idea (single item) and from list_feed_items (the raw feed), though it never uses an explicit verb like 'list' and never names those siblings 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?

It gives usable context: 'Search with q' and a workflow chain ('use an idea as the starting point for create_post, then move it on with update_idea'), which tells the agent what this tool feeds into. It stops short of explicit when-not conditions or naming get_idea/list_feed_items as alternatives for single-item or raw-feed retrieval.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds ordering ('newest first') and, importantly, pagination behavior ('Pass next back as cursor for more'), which annotations cannot convey. It is slightly vague in that the 'next' field is never formally defined anywhere (no output schema), leaving the agent to infer it comes from the response.

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 short sentences, front-loaded with the resource and ordering, then the filter, then pagination. Every sentence carries information; 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, five-parameter list tool with no output schema, the description covers purpose, ordering, the key filter, and pagination continuation. The only gap is the undocumented response field name for the cursor, which an agent must discover at call time.

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 80%, so the schema already documents q, limit and cursor. The description reinforces the meaning of 'unused' and explains cursor continuation, but adds nothing for q or type beyond the schema. This is the baseline case where the schema does the heavy lifting.

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

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

The description names the resource precisely ('Files already in this workspace'), its ordering ('newest first'), and its purpose ('reuse one by its id in media_ids'). It does not explicitly contrast with a sibling, but no sibling tool covers media, so the purpose is unambiguous in 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?

It gives a clear use case: look here before uploading again, and pass the id into media_ids. The 'unused' filter's condition is also stated. There are no explicit exclusions or named alternatives, which keeps it 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully covered. The description adds genuine behavioral value with the 'Unread first' sort order, which is not expressed anywhere in structured data. It stops short of disclosure about result volume, pagination, or whether notice types can be mixed in one response.

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

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

Two short, dense sentences with no filler; the scope statement leads and the ordering hint trails. 'From the app's bell' is slightly scenic phrasing, but it usefully anchors the agent to the right UI concept.

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

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

For a single-optional-boolean read tool with a fully annotated safety profile and no output schema, the description does the important work: it tells the agent what kinds of notices come back and how they're ordered. Only pagination or result-size expectations are missing, which is a minor gap at this complexity level.

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

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

Schema coverage is 100% with a single well-described boolean, so the baseline is 3. The description's 'Unread first' adds a small nuance about default ordering relative to the unread filter, but it does not clarify whether the flag reorders or restricts results, leaving a minor 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?

Names the resource (notifications from the app's bell) and enumerates the concrete notice types returned: published, failed, retrying, recovered posts plus accounts at risk of losing sign-in. The 'list' verb is implicit from the name but the scope is unmistakable, and no sibling tool overlaps with this resource, so differentiation is not a concern.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for surfacing alerts or account health issues, and 'Unread first' hints at the default ordering. There is no explicit when-to-use, when-not-to-use, or alternative named, but since no sibling tool covers notifications, the risk of misselection is low.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds non-obvious behavior the annotations cannot convey: the default time window, the dramatically widened window for draft/approval queries, and the meaning of each status (pending_approval waits on the owner, partial means some accounts failed). That is exactly the context needed to avoid missing drafts.

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 and front-loaded: the window default leads, the draft edge case follows, and the sibling pointer closes. The status enumeration partially duplicates the schema enum, though the added meanings justify most of it.

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 not describe the shape of returned post objects or whether drafts are always merged in by default, which leaves mild ambiguity in the opening sentence. The critical calling behavior — window defaults, status filtering, ordering, timezone — is fully 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 100%, so the baseline is 3; the description goes further by explaining that the from/to window is optional and what happens when it is omitted, and by glossing the status enum values semantically rather than just listing them. It does not add format detail beyond the schema's ISO 8601/unix notes.

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 makes clear this retrieves multiple posts constrained by a time window, and it distinguishes itself from get_post ("Use get_post for one post"). It is written as a noun fragment ("Posts in a time window...") rather than an explicit verb+resource statement, but the scope 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?

It states the default window (last 7 days to next 30 days), the special case (status=draft/pending_approval with no window widens to 90 days back through 5 years ahead), and the alternative for single-post retrieval. An agent can pick this tool and predict its behavior without guessing.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely new context the annotations cannot convey: results are aggregated across multiple surfaces (preview link, approval link, app/agents) and include replies plus counts. It does not mention pagination or ordering, which is a minor gap.

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 tight sentences, with the scope front-loaded before the disambiguation from list_comments. The middle clause is a dense list that reads as a fragment, but nothing 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 two-parameter read tool with no output schema, the description supplies enough: what is returned (threads with replies and counts), where from, and what the status filter means. Pagination/ordering behavior is the only notable omission.

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

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

Schema coverage is 100% and both parameters are already documented there, including the enum values and the 'open = not resolved' meaning. The description largely restates the status semantics rather than adding format or interaction detail, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('comment threads on one post') and enumerates the sources those threads come from (preview link, approval link, team in the app, agents). It explicitly names the sibling list_comments and explains how it differs, so an agent can separate the two without opening a 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?

The description gives a clear exclusion ('not comments people left on the platforms (that is list_comments)') and explains the status semantics, which guides selection. It does not, however, spell out when in a workflow an agent should reach for review comments versus, say, get_post or preview_post.

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 establish read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds value beyond them by disclosing the shape of the payload (tag name, colour, usage count), which matters because there is no output schema. It says nothing about ordering or limits, but for a small workspace-scoped list that is minor.

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

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

Two short sentences with no filler: the first defines the resource and its contents, the second supplies the workflow hook. Everything is front-loaded and nothing is redundant.

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 carries the burden of describing the return, and it names the three fields an agent needs. Combined with annotations covering safety, this is nearly complete; only ordering or volume expectations are unaddressed.

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 no parameters, so there is nothing to document; the schema coverage baseline of 4 applies. The description correctly does not invent parameters and instead uses the space to explain the return shape.

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

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

The description names the specific resource ('the workspace's post tags') and enumerates the fields returned (name, colour, post count), which clearly separates it from list_posts or list_templates. It never states the verb 'list' outright, relying on the enclosure to convey that this is a retrieval, but an agent can still tell what it gets back.

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 actionable downstream context: 'Pass names in tags on create_post or update_post', which tells the agent why it would call this and what to do with the result. There are no explicit exclusions or alternatives, but for a zero-parameter listing tool the guidance is clear enough.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds substantive behavior context beyond that: the composite shape of a template (accounts, text, first comment, per-account privacy and made-for-kids settings) and how its identifier feeds create_post. Return ordering/count is not mentioned, keeping it at 4.

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, no filler, with the content enumeration up front and the follow-up action second. The nested parenthetical listing account settings is a little dense but every clause carries 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 zero-parameter read tool with a full annotation set and no output schema, the description covers what the items are and how to act on them. What is missing is minor — whether the list can be empty, its ordering, or pagination behavior.

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?

This tool takes no parameters, so the baseline is 4. The only identifier mentioned, template_id, belongs to create_post rather than this tool, but its mention usefully explains linkage between the two calls.

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

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

The description names the resource precisely — templates the owner saved in the app — and enumerates their contents (accounts, text, first comment, per-account options), so an agent knows exactly what comes back. The verb is only implied by the name, and there is no explicit contrast with siblings like list_posts or list_ideas, which keeps it from a 5.

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?

"Pass template_id to create_post to start from one" gives a concrete downstream action, which is exactly the context an agent needs to decide to call this. It does not state when not to use it or how it differs from other listing tools, so it falls short of explicit 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 readOnly/idempotent/non-destructive, and the description goes well beyond them by enumerating what the preview returns per account: rendered text with signature and short links, length vs. limit with over_by, media, format, thread parts, first comment, problems and warnings, resolved time, approval wait, and the refusal payload. This is unusually rich behavioral disclosure for a no-side-effect tool.

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 key fact — same args as create_post, saves nothing — is front-loaded, and the long enumeration of returned fields is information-dense rather than padded. The middle sentence is a run-on list that could be broken up, but no clause is 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?

With 11 parameters, nested objects, and no output schema, the description compensates well by describing the return contents in detail. Remaining gaps are minor: nothing about authentication or what happens when no accounts or media are supplied, but an agent has enough 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 100% and the nested options object is documented exhaustively, so the schema carries the parameter burden. The description adds only that the argument set is identical to create_post and that values are resolved per account (signature, short links, resolved time), which is useful but not substantive parameter-level clarification beyond the schema.

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

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

The opening sentence states a specific behavior: it takes the same arguments as create_post and saves nothing, which is a dry-run verb+resource an agent can immediately distinguish from create_post and from the read siblings like get_post. The title reinforces it without being the only signal.

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?

"Use it to fix everything in one turn and to show the user each network's version" gives an explicit when-to-use and an intended workflow. The create_post relationship ("what create_post would answer instead") implicitly defines the alternative, but there is no explicit statement of when not to use it or of prerequisites such as needing accounts/media already uploaded.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds substantial context beyond that: which networks are queried, that X comments are excluded, that commenter suggestions appear on @handle networks, and exactly how to merge item.insert and item.mention into the post payload.

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 purpose is front-loaded and the remaining sentences carry non-obvious integration rules. The description is dense but largely earns its length; minor tightening could improve scanability, but it is appropriately sized for a multi-network lookup tool with no output schema.

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 network-specific complexity and lack of an output schema, the description supplies the critical usage rules and field names (item.insert, item.mention). It stops short of describing result ordering, pagination, or the full response shape, but it directs the agent to the answer for handle format examples.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description reinforces how account_id relates to list_accounts and implies query behavior, but it does not add new syntax or semantic detail beyond the schema's own descriptions.

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

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

The opening sentence states the resource and purpose precisely: people and pages to @mention in a post to one account. It distinguishes network-specific behavior, so an agent knows exactly what this tool returns and for which platforms. No sibling tool performs this lookup, so no explicit differentiation is needed.

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 when lookup is available and when it is not, including which networks have no lookup and what to do instead (ask the user for the full handle). It also says how to apply the results, but it does not explicitly compare alternatives or state a triggering condition like 'use this while composing a post'.

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