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

With only openWorldHint=true available in annotations, the description carries real behavioral weight: it discloses that tokens 'are stored only on this machine', what the call returns (authorize_url plus a note to relay), the human-in-the-loop requirement, and the exact follow-up call for each flow. That is substantially more than the single annotation conveys.

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-loads the action and return value, then splits the two flows into short labeled clauses. Every sentence is operative: no restatement of the name, no filler.

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

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

For a zero-required-parameter tool with no output schema, the description supplies everything an agent needs: what is returned, the human handoff, the per-mode follow-up call, and the trust boundary for token storage. The only open question is where 'mode' originates, which is a schema-side gap rather than a description 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?

Schema description coverage is 100% and the single parameter (wait_seconds) is fully documented in the schema, including default and maximum. The description never mentions wait_seconds or the blocking/return-immediately tradeoff, so it adds no meaning beyond the schema — 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?

Opens with a specific verb and technical mechanism ('Start OAuth 2.0 (PKCE) to authorize another X account'), naming the exact resource and the resulting artifact. An agent can distinguish this from complete_authorization (finishes the flow) and auth_status (checks it) without opening any 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?

Explicitly routes the agent to siblings: 'confirm with auth_status' for loopback and 'pass it to complete_authorization at once' for paste mode, which is genuine when-to-use guidance. It stops short of stating when an agent should prefer this tool over re-using an existing account, and the 'mode' selector it branches on is not present in the input schema, leaving the branch condition underspecified.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully discloses that the call can block ('optionally wait'), but says nothing about what the operation returns or what the terminal/failed states look like, which matters for a polling 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?

Two short sentences, zero filler, with the core condition (authorization started via add_account) front-loaded before the optional behavior.

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 should describe the status values returned and what to do on completion or failure; it does neither. It is adequate for a basic polling call but leaves the return contract entirely undocumented.

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 50%: 'state' is documented in the schema ('state returned by add_account') while 'wait_seconds' carries only min/max bounds. The description partially compensates by framing the wait as optional, but gives no units, blocking semantics, or timeout guidance beyond the implied parameter name.

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 ('check') plus resource ('whether an authorization... has finished') with the triggering sibling named explicitly ('started with add_account'). An agent can distinguish this from add_account, complete_authorization, and list_accounts without opening any 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?

Clearly states the context: use it after add_account to poll for completion, and notes the optional wait behavior. It does not address when to prefer this over complete_authorization (the redirect/callback path) or how often to poll, so it falls short of explicit alternatives/exclusions.

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

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

Annotations only declare openWorldHint=true, so the description carries the behavioral burden. It adds genuinely useful, non-obvious context: the callback URL must contain code and state, and the X codes expire ~30 seconds after approval, which is a critical timing constraint for the agent. It omits what happens on failure/expiry, so it is not exhaustive.

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 fallback condition front-loaded, followed by the time-sensitive expiry warning. No filler; each clause carries information, though the phrasing is slightly dense.

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 OAuth-completion tool with no output schema, the description covers the trigger, the value's source and contents, and the expiry constraint. It could note expected results or expiry behavior, but nothing essential for invocation is missing.

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

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

Schema coverage is 100% and the parameter already has an example, so the schema does the heavy lifting (baseline 3). The description adds meaning by telling the agent where to obtain the value (the browser address bar) and what it must contain (code and state).

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 gives a specific verb+resource (finish/complete the add_account authorization) and explicitly frames itself as the fallback path versus the automatic callback listener. An agent can distinguish this from the sibling add_account and other account tools 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 clearly states the trigger condition: use this when the automatic callback listener is unavailable. The alternative (the automatic path) is implied, but there is no explicit 'do not use this in the normal flow' exclusion, keeping it just short of a full 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 only declare openWorldHint, so the description carries most of the load and does add real value: pay-per-use credit consumption, an approximate per-post cost, a surcharge when the text contains a URL, and a pointer to current pricing. It also implies upload side effects for media_files ('uploads for you'). It stops short of describing failure modes or what post-creation returns.

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

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

Three dense sentences, no filler, with purpose and the reply/media affordances front-loaded and the cost/precondition caveats last. Slightly packed with parenthetical detail but nothing that fails to earn its place.

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

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

For a 10-parameter, no-required-parameter mutation tool with a nested poll object and no output schema, the description covers the operationally critical unknowns: cost, confirmation precondition, and media sourcing. Parameters like poll, reply_settings, quote_post_id, and the AI/partnership disclosures are left entirely to the schema, which is acceptable at 90% coverage.

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 90%, so the schema already documents nearly all ten parameters. The description adds only a light gloss: that reply_to_post_id is the reply mechanism, and that media_files uploads on the caller's behalf versus media_ids referencing existing uploads. That is a modest increment over the schema, matching the baseline 3.

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 (publish a post) plus the acting scope (as the given account) and a second mode (reply via reply_to_post_id). An agent can distinguish this from siblings like create_thread, delete_post, or post_action without opening any 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?

Gives an explicit gating precondition: 'Only call when the user has confirmed the exact text and account.' It also clarifies the reply use case. It does not, however, route the agent among alternatives such as create_thread for multi-post threads or upload_media for pre-staged media.

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

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

Annotations only declare openWorldHint=true, so the description carries the burden and does well: it discloses partial-failure semantics ('stops at the first failure and reports what was posted') and billing behavior ('billed like create_post'). It does not cover authorization requirements or rate limits, but the failure/billing disclosure is genuinely valuable.

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 core action, followed by failure behavior and billing. No filler, and each sentence conveys a distinct fact.

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

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

For a mutating tool with no output schema and a nested posts array (1-25 items), the description supplies the sequencing rule, the stop-on-failure contract, and the cost model. The remaining gap is that it says what was posted is reported but gives no shape of that report.

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 67% and already documents account and reply_to_post_id. The description adds the key missing semantic for the posts array: it is ordered, with each entry replying to the prior one. That ordering/chaining meaning is not derivable from the schema alone.

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

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

It states a specific verb and resource (publish a thread) and immediately clarifies the semantics: each post replies to the previous one. This implicitly separates it from create_post, but it never names the sibling, so the differentiation is inferential 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?

Usage is only implied: an agent can infer this is for multi-post chained publishing rather than a single post. There is no explicit when-to-use/when-not guidance or a pointer to create_post as the alternative for a single 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?

Annotations already declare destructiveHint, idempotentHint and openWorldHint, so the bar is lower. The description still adds genuinely non-annotated context: the operation is billed per request and is scoped to a post the given account owns, which matters for retry/cost decisions and for pre-call authorization.

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 13-word sentence with the action front-loaded and the two addenda (ownership, billing) appended compactly. No filler, nothing to trim.

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-required-parameter destructive call whose annotations already carry the safety semantics and which has no output schema, the description covers purpose, cost, and ownership scoping. Remaining gaps (permanence/irreversibility, error cases) are minor given the annotation coverage.

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 50%: 'account' is well documented in the schema (references list_accounts and the default-account behavior) while 'post_id' has no description at all. The description only implies a constraint — that post_id must reference a post owned by the account — without clarifying identifier format or failure behavior, so it neither compensates nor falls below the baseline.

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

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

States a specific verb and resource ('Delete a post') with an ownership scope ('owned by the given account'), which is unambiguous. It does not, however, differentiate itself from nearby siblings such as post_action or create_post, so the agent gets no explicit routing cue.

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 when-to-use / when-not-to-use guidance and no alternative tool is named. The agent must infer that post_action or other post-mutating siblings are not the right choice for deletion.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a small behavioral note that the owned mode defaults to the account, which is useful context, but discloses nothing about rate limits, auth requirements, or the differing return shape per mode.

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 telegraphic fragments with no wasted words, and the mode enumeration is front-loaded right after the verb. The staccato style is slightly cryptic but earns its place by packing mode/purpose into one line.

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 6-parameter, four-mode tool with no output schema, the description omits what each mode returns, how max_results and pagination_token interact, and any auth context. The one required parameter is explained, but an agent still lacks enough to invoke it confidently across modes.

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 67% schema coverage the schema documents user/account/max_results/pagination_token but leaves list_id bare and never maps which parameters apply to which type. The description supplies exactly that mapping (owned consumes user, while info/members/posts consume list_id), adding real meaning beyond the schema.

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

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

"Read Lists" is a thin verb+resource; the real content is the enumeration of the four type modes (owned/info/members/posts). It clarifies the modes but does not distinguish this tool from siblings like list_action or get_posts, and never states what a "List" is in this API. Adequate but not sharp.

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 names the type values but gives no when-to-use guidance: it never says whether to reach for get_lists versus list_action, get_posts, or search. No prerequisites, no exclusions. The enum list is closer to parameter documentation than usage 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: the underlying endpoint and the billing consequence ('billed as a user read'), which is a real cost consideration for an agent deciding whether to call.

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 tight sentence, front-loaded with the action and resource, with the endpoint and billing note appended. 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?

A simple parameterless read whose safety profile is carried by annotations and whose parameter is fully documented by the schema. The description covers purpose, endpoint, and billing, leaving no material gap for an agent 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 coverage is 100% and the single 'account' parameter is well documented in the schema itself. The description adds no parameter meaning, 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?

States a specific verb+resource ('Fetch the authenticated user's profile') and pins the exact endpoint (GET /2/users/me). 'Authenticated user's' implicitly distinguishes it from sibling get_users, though it never names that sibling 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?

No when-to-use or when-not-to-use guidance. It doesn't explain how this differs from get_users or when to reach for it over other user tools; the agent must infer everything from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds that this is about asynchronous processing of uploaded media, which hints at polling behavior, but it never states whether status is transient, whether it can fail, or how long processing takes.

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 with zero filler. It is efficient, though its brevity borders on under-specification for a tool whose usage pattern needs explanation.

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 should describe the possible statuses (e.g., processing/ready/failed) and what the agent should do next. None of that is present, leaving the caller unable to interpret results for a two-parameter tool.

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

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

Schema coverage is only 50%: the account parameter is documented but media_id has no schema description, and the tool description does not compensate by explaining that media_id comes from upload_media. With low coverage, the description should carry this burden and does not.

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 (check) and resource (processing status of an uploaded video/GIF), which is clearly distinct from upload_media and other siblings. It does not explicitly name the sibling it complements, but the purpose is unmistakable.

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

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

No when-to-use guidance is given. The description never says this should be called after upload_media, that it is a polling operation, or what to do with the result, all of which are the key usage decisions for a status-check 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully clarifies that types return different entities (users vs. quote posts), but says nothing about rate limits or pagination behavior despite pagination params existing.

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, zero waste, and the core purpose is front-loaded ahead of the type breakdown.

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

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

For a simple read tool with annotations covering safety, the description is mostly sufficient. However, pagination (pagination_token / max_results) and the return shape are not addressed, and no output schema exists to offload them.

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 60%, so the description needs to add value. It does clarify the semantics of the 'type' enum (repotted_by returns users, quotes returns quote posts), but leaves account, max_results, and pagination_token to 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+resource ('get post engagement') and immediately clarifies the three modes it returns. It is clear what the tool does, though it does not explicitly differentiate itself from siblings like get_posts or get_timeline.

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

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

Usage is implied by 'who engaged with a post' rather than stated. There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named, but the intent is inferable from the description.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds non-obvious behavioral context not in the annotations: batch cap of 100 IDs and 'Billed per post', which warns the agent of a per-item cost. Pagination/return shape is not discussed, keeping 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?

A single tight sentence with the key constraint (by ID) and the cost caveat front-loaded and no filler. Every clause earns its place.

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

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

For a read-only lookup with annotations covering safety and no output schema, the description usefully enumerates the returned data (author, metrics, media, referenced posts) and the billing behavior. Only pagination/formatting details are absent, which is minor 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?

Schema coverage is 50%: 'account' is fully documented in the schema while 'ids' has only type/maxItems/minItems and no description. The description compensates by clarifying the ID range (1-100), which matches maxItems, so it adds some value but leaves ID format unstated.

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 (look up), resource (posts), and access method (by ID) with the batch range 1-100, plus the return contents. That implicitly separates it from search and get_timeline, though it never names a sibling explicitly, 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?

No explicit when-to-use or when-not-to-use guidance. 'By ID' implies it's for known IDs versus search/timeline discovery, but no alternative is named and no prerequisites are given. The billing note hints at cost-awareness but is not framed as usage guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the description's real contribution is 'Billed per post returned' – a cost consequence the agent cannot see anywhere else and which should discourage oversized page requests. It adds nothing about auth or rate limiting beyond that, keeping it at 4 rather than 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?

Four compact clauses, no filler, with the resource, the enum glossary, the default, and the billing constraint all front-loaded. Every sentence carries information an agent needs before calling.

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 read tool with no output schema, the description names the resource, enumerates the type domain, states a default, and warns about per-post billing. What is missing is any hint of what a returned post/page looks like or how pagination_token chains pages, which the schema implies but never explains.

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 75%, and the description covers the biggest semantic gap: it defines each enum value of `type` (the only required param) and states that `user` defaults to the caller's own account. It adds nothing for `exclude`, `start_time`/`end_time` or pagination, which the schema already handles.

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

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

The description opens with a specific verb+resource ('Read a timeline') and enumerates every accepted type with a parenthetical meaning, so the agent knows exactly what is retrieved. It does not explicitly differentiate itself from the sibling get_posts, which is the obvious adjacent read tool, so it falls 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?

The type-by-type annotations ('home (your reverse-chronological home feed)', 'liked (posts a user liked)') effectively tell the agent which value to pick for which content need, and the defaulting rule for `user` is stated. There is still no explicit when-not or named alternative such as get_posts or search, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that - no indication of the return shape, whether trends are region/time-windowed, freshness, or rate-limit behavior for an open-world read.

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 short sentence with no filler, front-loading the resource. It is efficient, though arguably under-specified rather than tightly scoped.

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 one-optional-parameter read tool with annotations covering safety and no output schema, the description is minimally adequate. It leaves the nature and scope of the returned trends undefined, which is the main 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?

Schema description coverage is 100%, and the single optional 'account' parameter is fully documented in-schema with a pointer to list_accounts. The description adds no additional meaning, 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 name and description together convey retrieval of trend data, and 'Personalized ... for the account' hints at account-scoped results. However, the phrasing is vague about what a 'trend' actually is (hashtags, topics, posts?) and offers no differentiation from siblings, though no sibling appears to cover trends.

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?

No when-to-use guidance, no prerequisites, no alternatives named (e.g., get_timeline or search for non-personalized discovery). The only hint is that trends are account-scoped, which the agent must infer from the word 'Personalized'.

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 and openWorldHint, so safety is covered. The description adds a real behavioral nuance beyond them: only the account's own muting/blocking list is exposed, and the default target is the authenticated account. It says nothing about paging behavior or result ordering, so it adds moderate context but not rich disclosure.

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

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

A single, front-loaded sentence covering all four relation modes plus the default-target caveat. Slightly dense with parentheticals, but every clause earns its place and there is no 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?

No output schema exists, but the description plus the well-documented schema are enough for an agent to call this correctly: the mode is enumerated, the target/default is explained, and paging inputs are described in the schema. Remaining gaps (return shape, ordering) are minor for a read-only list operation whose safety profile is already in annotations.

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 user, account, max_results, and pagination_token in detail. The description only contributes the default-user semantics and the ownership constraint on muting/blocking; the baseline of 3 is appropriate when the schema carries most of the parameter meaning.

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

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

The description gives a specific verb ('List') and resource ('followers or following... muting/blocking list'), and the four enumerated relation types map exactly onto the 'type' enum, so the agent knows what the tool returns. It stops short of naming a sibling it must not be confused with (e.g., get_users or user_action), so it is clear but not sibling-differentiated.

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 one useful usage fact: the target defaults to the account itself when no user is given, and that muting/blocking is the account's own list. There is no explicit when-to-use/when-not guidance relative to user_action, get_users, or list_accounts, 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?

Annotations already establish readOnlyHint and openWorldHint, so safety is covered. The description adds a genuinely non-derivable behavioral fact: the call is billed per user, which materially affects how an agent should batch lookups. It stops short of 5 because it says nothing about auth/permission requirements or partial-failure behavior for unknown usernames.

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, front-loaded with the lookup keys, and the billing caveat placed last where it belongs. No filler.

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

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

For a three-parameter read tool with no output schema, the description covers the core lookup behavior and cost, but omits the account parameter, any indication of what profile fields come back, and how unknown or duplicate identifiers are handled.

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 only 33%, so the description must compensate, and it does partially: it clarifies that ids are numeric identifiers and that usernames are the alternative key, plus the 100-item cap (already in maxItems). It says nothing about the undocumented account parameter, and its "numeric IDs" phrasing slightly tensions with the schema's string-typed items.

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

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

The description names a specific verb and resource ("Look up user profiles") and states the two accepted lookup keys (usernames, numeric IDs), so the agent knows exactly what the tool returns conceptually. It does not distinguish itself from siblings like get_me or get_user_relations, 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?

It explains how to call it (by usernames or IDs) but never when to prefer it over alternatives such as get_me for the authenticated user or search for discovery. No prerequisites, exclusions, or sibling routing are given, so usage must be inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond them: the data comes from the local machine and incurs no API cost, implying no network round-trip, no auth handshake, and no rate-limit exposure. It stops short of describing what a returned account record contains.

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 no filler, front-loading what is listed and following with the operational constraint. 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-only local listing with no output schema, the description covers purpose, scope, and the cost/network constraint. The only minor omission is the shape of returned account records, which is acceptable for a straightforward enumeration.

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 schema has nothing to document and the baseline is 4. There is no parameter behavior the description needs to clarify.

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 (X accounts), plus the extra fact returned (which account is default). An agent can distinguish it from add_account, remove_account, and set_default_account without opening any 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?

"Local only, no API cost" signals that this call is cheap and safe to invoke freely, which is useful usage context. However, it never names an alternative or states when to prefer this over siblings such as auth_status or get_me, leaving the 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?

Only openWorldHint=true is annotated, so the description carries the full behavioral burden and fails it. It never states that four of the five actions mutate or destroy data, whether delete is irreversible, what permissions or account authorization are required, or what happens to members on delete.

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 compact sentence that front-loads the resource and the operation set with no filler. It is efficient, though it duplicates the enum verbatim rather than earning that space with new 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 7-parameter mutation dispatcher with no output schema and low schema coverage, the description omits per-action parameter requirements (e.g. list_id required except create, user only for member actions) and all behavioral caveats. An agent cannot call this safely from the description alone.

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 only 43%, so the description would need to compensate for name, list_id, private, and description. It adds nothing for those fields and only repeats the action values already enumerated in the schema enum.

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 (X Lists) and enumerates the five operations, which is a clear specific scope beyond the ambiguous name 'list_action'. However, it never distinguishes this tool from the read-side sibling get_lists, leaving the boundary implicit.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as get_lists for reading or list_accounts for accounts. The action list is simply a restatement of the schema enum, so an agent gets no routing help.

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

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

Annotations only provide openWorldHint and idempotentHint; notably there is no destructiveHint, so the mutation surface is not covered structurally. The description adds a useful scoping detail for hide_reply/unhide_reply ('replies to your own posts'), but says nothing about reversibility, permission requirements, or failure behavior beyond what the action pairs imply.

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 states the interaction target first and then the available verbs. No filler, no repetition, appropriately sized for 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?

For a mutation tool with no output schema and thin annotations (no destructiveHint), the description leaves gaps: post_id provenance and format, account resolution, and what a call returns or how errors surface. It is adequate to select the tool but incomplete for confident 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 coverage is only 33% (account is the sole documented parameter), and the description merely re-lists the action enum values already present in the schema, which earns no credit. Only the parenthetical about own-post replies adds semantics; post_id's expected format (ID vs URL) is left entirely undefined in both places.

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

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

The description names a specific resource (a post) and fully enumerates the eight supported verbs, so an agent knows exactly what the tool mutates. It is clearly separable from create_post/delete_post and from the sibling user_action, though it does not explicitly call out that distinction.

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 when-to-use guidance: no mention of how to obtain post_id (e.g., via get_posts or search), no note that account must come from list_accounts (that hint lives only in the schema), and no exclusion conditions. Usage must be inferred entirely from the action names.

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 destructiveHint=true and openWorldHint=true, so the destructive/remote profile is covered structurally. The description adds useful context that tokens are revoked at X (an external side effect matching openWorldHint), but it omits irreversibility, re-authorization requirements, and failure behavior if the account is unknown. Adequate but not rich.

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 tight sentence with the primary action front-loaded and the side effect second. No filler, though the phrase 'on this machine' plus 'at X' is slightly awkward and could be sharpened rather than saving space.

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 destructive, two-parameter mutation this covers the essentials: what is deleted and that remote tokens are revoked, with annotations carrying the safety profile and no output schema to explain. It's still thin on reversibility, permission/auth prerequisites, and the meaning of the undocumented 'account' parameter.

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 50%: the 'revoke' boolean is documented in the schema (including its default true), while the required 'account' string has no description in either place. The description's mention of revoking tokens at X loosely signals the 'revoke' behavior but adds no format or identification detail for 'account'. 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+resource ('forget an authorized account') and adds the remote effect ('revoke its tokens at X'), which clearly distinguishes it from siblings like add_account, list_accounts, set_default_account. It stops short of naming a sibling to contrast against, so 4 rather than 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?

The phrase 'on this machine' implies the operational context (de-authorizing a locally configured account), so usage is indirectly inferable. However, there is no explicit when-to-use or when-not guidance relative to siblings such as add_account or set_default_account, and no prerequisites 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 and openWorldHint. The description adds genuinely non-redundant behavior: the 7-day recency window for posts and the fact that results are billed per post returned, which is important cost/limit context not derivable from schema or annotations.

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

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

Very tight, front-loaded to the search modes with the billing caveat attached where relevant. No wasted sentences, though it is arguably terse enough to omit useful detail.

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

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

Covers the two search modes and the key constraint (7-day window, billing). With read-only annotations present and 88% schema coverage, the gaps are minor—pagination via next_token and return shape are unaddressed, but no output schema exists to require that.

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 88%, so the schema already documents types, ranges, enum values, and query syntax; the description adds the posts 7-day window but little else. Baseline 3 applies when 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?

'Search X' states a specific verb and resource, and it distinguishes its two modes explicitly (type=posts vs type=users). It does not differentiate from siblings like get_posts, get_timeline, or get_users, so it falls 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?

Usage is implied via the type enum descriptions and a cost-oriented hint ('keep max_results small'), which helps bound usage. However there is no explicit guidance on when to choose this over get_posts/get_timeline/get_users, so it stays at an implied level.

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 openWorldHint=false and idempotentHint=true, and the description reinforces them by disclosing 'No API call' and that the value is persisted locally on the machine. It does not state whether an existing stored client ID is overwritten, but the local-persistence detail meaningfully adds to the structured hints.

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 core action and ending with the practical constraints ('Needed once before add_account. No API call.'). Every clause earns its place with no redundancy.

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 need not explain returns, and the precondition/timing context is fully covered. The only gap is guidance on the optional client_secret parameter, though the schema description partially covers that.

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 50%: client_secret is documented in-schema ('Only for Web App (confidential) clients'), while client_id is bare. The description adds helpful context for client_id (its origin at console.x.com and OAuth nature) but never mentions client_secret or when it is required, so it only partially compensates for the coverage 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?

States a specific verb and resource ('Save the OAuth 2.0 Client ID of the user's own X App') plus the storage scope ('on this machine'), so it is clearly distinct from siblings like add_account and complete_authorization. An agent can identify exactly what this does 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?

Explicitly states when this is needed ('Needed once before add_account') and the selecting condition ('for hosts that cannot pass the X_CLIENT_ID environment variable'), which is effectively the alternative path. Nothing about timing or precondition is left to inference.

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

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

Annotations only cover idempotentHint and openWorldHint; the description adds the non-obvious behavioral consequence that this setting governs calls that omit `account`, plus an implicit authorization requirement. It still omits persistence scope and error behavior for an unauthorized account, so it is helpful but not complete.

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 with the core semantic effect in the first clause. Every word earns its place and nothing is padded.

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

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

For a one-parameter setter with an output schema absent, the description conveys what the setting does and when it applies. The remaining gap is how to obtain a valid account value and what happens on failure, which would make it fully self-sufficient.

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

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

Schema coverage is 0% and the single `account` param is an undescribed string. The word "authorized" narrows the acceptable values (it must come from the user's linked accounts), which is real added meaning, but no format (handle vs id vs username) or discovery hint is given.

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 (set/choose) and resource (the default authorized account), and goes further by explaining the effect: the account used when a call omits `account`. It is unambiguous against write-style siblings like add_account/remove_account, though it never names an alternative.

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 agent can infer this is the fallback-account setter, and that the account must already be authorized. There is no explicit when-to-use versus list_accounts/add_account, nor any prerequisite or failure condition 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 only provide openWorldHint, so the description carries the behavioral burden and does so well: single-request vs chunked upload thresholds, that GIFs/videos wait for processing, and that alt text is optional. It omits auth/account prerequisites and any failure or retry behavior, keeping it out of 5 territory.

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

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

Three dense sentences with the purpose, return value, and operational constraints front-loaded; every clause earns its place and nothing is padded.

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

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

Covers input types, size thresholds, async processing, output identifier, and the follow-up tool, which is substantial for a 6-param tool with no output schema. Missing pieces are account/authorization context and what to do while processing, so it is strong but not exhaustive.

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

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

Schema description coverage is 83%, so the schema already documents base64, account, file_path, mime_type, and media_category. The description adds only that alt_text is optional and restates the output id; it contributes little parameter-level meaning beyond structured fields, matching the baseline.

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

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

Names a specific verb+resource (upload media), states the accepted file types, and declares the return value (media_id) plus its downstream consumer (create_post). This distinguishes it cleanly from siblings like get_media_status or create_post.

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?

Clear context: use this to obtain a media_id for create_post, with size/type conditions that dictate the upload path. It does not name an explicit alternative or when-not-to-use case (e.g., checking status via get_media_status), so it stops short of a top score.

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 declare openWorldHint=true and idempotentHint=true, so the external-call and repeat-safety profile is already given. The description adds a genuine behavioral caveat that block may be refused on pay-per-use apps, which is valuable. However, it does not disclose permissions, reversibility of block/mute, or what happens to an already-followed user.

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: the operation list is front-loaded and the Enterprise caveat follows as a scoped qualifier. No filler or redundancy; every clause earns its place.

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

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

For a mutation tool with no output schema and only partial annotation coverage (no readOnly/destructive hints), the description is adequate but leaves real gaps: it doesn't say the action requires an authorized account beyond the schema hint, doesn't describe failure behavior for non-Enterprise block, and doesn't cover the remaining parameter documentation 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?

Schema coverage is 67% and the schema already documents both 'user' and 'account' and enforces the action enum. The description's Enterprise caveat adds meaning for the 'block' enum value and 'as the given account' reinforces the account param, but it stops short of compensating for the remaining undocumented parameter detail.

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 (user) and enumerates the exact operations (follow, unfollow, mute, unmute, block, unblock), so an agent immediately knows it is a user-relationship mutation tool. It doesn't explicitly contrast with siblings like post_action or list_action, but the resource scope is clear enough to disambiguate.

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 Enterprise-only note about block is a useful bring-your-own-conditions caveat, but there is no explicit guidance on when to use this vs. related siblings (e.g., get_user_relations) or prerequisites beyond the schema's account param. Usage is implied by the action list rather than stated.

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