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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds useful behavior: it returns {ok, expires_at, seconds_remaining, user_id} or {ok: false, error} when the JWT is missing or expired. It does not clarify failure behavior for an invalid lastRequestId, so it stops short of full transparency.

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

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

The description is two sentences: the first states the purpose, the second states the return shape and error case. It is front-loaded, precise, and every sentence earns its place.

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

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

There is no output schema, and the description competently describes the return object and error object. However, it only mentions the error case for a missing or expired JWT, leaving the failure behavior for an invalid lastRequestId unspecified. This is a minor but real gap for a tool that claims to verify both values.

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

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

The tool has zero parameters, so parameter semantics are not applicable and the baseline is 4. Mentioning JWT and lastRequestId from .env provides useful context but does not describe any input parameter 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 states a specific verb and resource: 'Verify the JWT and lastRequestId in .env are still valid.' It clearly distinguishes the tool from unrelated social-media siblings and tells the agent exactly what operation is performed.

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 the phrase 'still valid,' suggesting a pre-flight or session-check context, but the description provides no explicit when/when-not guidance or alternatives. For a zero-parameter auth check, this is minimally viable but leaves the agent to infer timing.

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 safety profile is fully covered elsewhere. The description adds nothing beyond that: no pagination limits, no ordering caveats, no indication of how many comments are returned per page.

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 fragments, fully front-loaded, with zero filler. It is terse to the point of omitting useful context, 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 simple read-only list tool with a complete input schema and no output schema, this is minimally adequate. However, return shape and pagination behavior across pages are left entirely unexplained, which an agent needs to page 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%, so the baseline is 3. The description merely restates required/optional status and the oldest_first default, which the schema already documents, adding no new semantic meaning such as the page size or ordering interaction.

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 resource and action: a comment list scoped to a post. An agent can tell it retrieves comments rather than posts or users, though it does not name a sibling tool or contrast with get_post_details which might also surface comment data.

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 only implies usage through the required post_id mention. It offers no when-to-use guidance, no prerequisites (e.g. auth or post visibility), and no pointer to an alternative if a different comment view is wanted.

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, openWorld and non-destructive, so the safety profile is covered. The description still adds real value beyond that: it discloses the return shape {count, has_next_page, view_options, posts}, the cursor contract, and several non-obvious defaults (only_with_image=true, limit=21).

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 dense but front-loaded block: purpose first, then required parameter, then optional parameters, then return shape. For ten parameters this is compact, though the run-on parameter list is harder to scan than a short list would be.

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 correctly compensates by naming the top-level response keys and the pagination field, and it covers the required tag plus every optional flag. An agent has enough to call and page through this 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%, so every parameter is already documented in the schema and the baseline is 3. The description largely restates those defaults and only adds the Cursor mechanics, which the schema also carries.

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 ('Fetch the post feed for a tag') and adds domain scope ('the homepage + category pages'), so an agent immediately knows this is category-browsing rather than a keyword query. It never names or contrasts a sibling such as 'search' or 'promoted_posts', which is the only thing keeping 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?

Usage is implied rather than stated: the tag-based framing and the pagination hint ('pass the last item's updateDate to get the next page') tell an agent how to page, but not when to choose this over 'search' or 'promoted_posts'. No exclusions or prerequisites are given.

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 write/idempotent/open-world profile, so the bar is lower, and the description adds real value beyond them: it discloses that the result is the new is_following state (no output schema exists to carry this) and that repeated calls toggle rather than set, which is exactly why idempotentHint=false. It still says nothing about idempotency-adjacent edge cases like following yourself or rate limits.

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

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

Three short sentences, front-loaded with what the tool does and the toggle semantics, with no filler. The 'Required: username' clause mildly duplicates the schema's required array, which is the only small 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?

For a one-parameter tool with a full annotation set, the description covers the verb, the toggle semantics, the required input, and the return value (important given no output schema). Nothing an agent needs in order to call it correctly 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 description coverage is 100% and the single parameter is documented in the schema itself ('Haraj username to follow/unfollow'), so the schema does the heavy lifting. The description restates that username is required but adds no format, casing, or identifier-type 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?

The description names a specific verb pair and resource ('Follow (or unfollow) a user'), which is the key detail an agent needs since the operation is a state toggle rather than an absolute set. It does not explicitly name the sibling it is not, such as is_following_user, but the verb+resource pair 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?

Usage is implied by the verb itself, and the toggle behavior hints at the condition under which it flips state, but there is no explicit guidance on when to call this versus the read-only sibling is_following_user, nor any mention of prerequisites such as authentication or target-user existence.

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 bar is lower, and the description still adds real value: it discloses that the response bundles three categories of related data and that 'full' toggles between the full similarPosts response and a summary. It omits cost/size implications of that bundling, but the response-shape disclosure goes beyond the annotations.

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

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

Three tight sentences, front-loaded with what is returned and the canonical-id framing, then the required parameter, then the flag behavior. No filler, no repetition of the tool name.

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

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

With no output schema, the description carries the return-shape burden and does so by enumerating the post plus the three related groups, and it explains the one non-obvious flag. Only minor gaps remain, such as pagination or response size for the full mode.

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 with types, defaults, and an example id, making 3 the baseline. The description's note that full defaults to true and controls similarPosts verbosity largely restates the schema rather than adding meaning beyond it.

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

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

States a specific verb (Fetch) and resource (a post) plus the exact payload shape: post + three related groups (similar posts by tag/city, similar images, related offers). It also preempts confusion with siblings by declaring itself the canonical 'fetch by id' operation, so an agent can distinguish it from post_contact, post_like_info, or comments 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?

Tells the agent this is the canonical by-id retrieval path and notes there is no direct getById in the GraphQL API, which answers the 'when do I use this' question. It does not, however, name sibling alternatives or state exclusions (e.g., use comments/post_contact for those resources), so it stops short of full when/when-not 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description usefully adds that the result is a true/false boolean scoped to the authenticated user, which compensates for the absent output schema, but it says nothing about failure modes, missing tags, or unauthenticated 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?

A single, front-loaded sentence that states the check and the return type with no filler. Nothing could be cut without losing 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 two-parameter boolean read tool with full schema coverage and rich annotations, the description covers the essentials, including the return type that would otherwise be missing without an output schema. Only the optional city scoping and edge-case behavior go unmentioned.

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%, with both `tag` (required, Arabic tag name) and `city` (optional scoping region) fully documented in the schema. The description adds nothing about parameters, so the baseline 3 applies; notably it never hints that a city scoping option exists.

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 check (follow status of a tag) and even names the return value (true/false), which is more than a tautology. It implicitly separates itself from sibling is_following_user by specifying a tag rather than a user, though it never names or contrasts 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?

Usage is implied by the purpose – an agent reading it knows to call it when it needs a boolean follow check for a tag. However, there is no explicit when-to-use, no when-not-to-use, and no mention of alternatives such as is_following_user or related_tags.

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 safety profile is fully covered. The description adds one genuinely useful behavioral detail, that the relationship is evaluated from the authenticated user's perspective, but says nothing about behavior for nonexistent users or whether an auth failure is surfaced as an error.

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 sentence with zero filler, front-loading the return type and the subject of the query. Nothing could be removed without losing meaning.

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

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

For a one-parameter boolean predicate with no output schema, the description tells the agent what it returns (true/false) and whose perspective it uses, which is enough to call it correctly. Minor gaps remain around auth requirements and unknown-user 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?

Schema description coverage is 100% and the single `username` parameter is already documented in the schema as a Haraj username. The description merely echoes the parameter name, adding no format or resolution semantics beyond it, 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 predicate (true/false) over a specific resource (follow relationship between the authenticated user and `username`). It is clearly distinguishable from the mutation sibling `follow_user` by the boolean framing, 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?

There is no when-to-use guidance, no stated preconditions (e.g. must be authenticated), and no routing to alternatives such as `follow_user` or `is_following_tag`. Usage is only inferable from the predicate wording.

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 openWorld behavior, so safety is covered. The description adds the returned field list and the server-side cap on limit, but says nothing about auth requirements, pagination, error behavior, or what happens if no streams are live.

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, front-loaded sentences with no filler; the resource and return shape come first. 'Non-GraphQL REST endpoint' is the one line of marginal value to an agent, but it costs almost nothing.

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

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

With no output schema, the description compensates by naming the return fields, and the single optional parameter is fully covered by the schema. For a simple read-only list tool this is nearly sufficient, though it omits empty-result and auth context.

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

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

Schema description coverage is 100%, so the single limit parameter is already documented with its default and server cap. The description only restates this, adding no syntax, range, or edge-case guidance 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?

Names a specific resource and scope: 'currently-open haraj live shopping streams', which is clearly distinct from siblings like fetch_feed, trending_keywords or promoted_posts. No explicit verb ('list') and no direct sibling callout, 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?

The 'currently-open' qualifier implies when the data is relevant, but there is no when-to-use guidance, no exclusions, and no mention of alternatives for closed streams or other feed tools. The agent must infer routing entirely.

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 no destructiveness, so the safety profile is covered structurally. The description adds nothing beyond that — no info on whether the offer is live, cached, region-dependent, or what triggers eligibility. For an openWorldHint tool, the external-dependency behavior is undisclosed.

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 short, but the leading curly-brace fragment is undecodable without reading the name and reads like an internal note rather than a front-loaded purpose statement. Brevity here comes at the cost of clarity.

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 tool with no output schema, the description should at least confirm that it returns an offer object and state its meaning. Instead it leaves the action, the domain concept, and the return semantics all implicit, which is insufficient even for a one-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 100% and the single parameter 'post_id' is documented ('Haraj post id.'). The description only repeats the requirement without adding format, valid-range, or sourcing detail — baseline 3 applies when the schema carries the load.

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 literal return-shape stub ('{offerId, isEligible, price}') rather than stating a verb and resource. It never says what the tool actually does — retrieve or request a Locker shipping offer for a post. An agent must infer the action from the name alone, and no sibling is 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?

The only guidance is 'Required: post_id,' which restates the schema's required field. There is no indication of when to call this versus get_post_details or other post-related siblings, and no context about what a 'Locker shipping option' means in the domain.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and openWorldHint=true, so the mutation profile is covered structurally. The description adds that set_read persists the change 'on the server', which is a modest but real behavioral detail beyond the annotations. It does not describe volume, ordering, or return 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?

Two short sentences, no filler. The resource identification is front-loaded and the parameter behavior follows immediately. Every word 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 one-parameter read/mark-read tool with no output schema, the description covers the essentials but omits what the tool returns (notification list shape, counts, pagination) and any usage context. Adequate but with clear gaps.

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% for the single set_read parameter, and the description largely mirrors the schema ('marks them as read on the server') plus the default. Baseline 3 applies since the schema already documents the parameter fully and the description adds no syntax or semantics beyond it.

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

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

The name 'notes' is opaque, but the description corrects this immediately with a specific resource: 'User notifications (the bell icon)'. It also names the optional mutation behavior via set_read. No sibling tool covers notifications, so no further 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 never says when to call this tool, in what context (e.g., polling for user activity), or what alternatives exist among the many sibling tools. Nothing beyond the implied 'use this to see notifications' is provided.

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, destructiveHint=false and openWorldHint=true, so the safety and side-effect profile is fully covered. The description adds only the pagination default, which the schema already documents. Given annotations carry the behavioral burden, a 3 is appropriate.

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

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

Very short, front-loaded with the resource identity and followed by the optional pagination note. No wasted sentences, though the branded parenthetical is slightly ornamental.

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-param read tool with full annotation coverage and no output schema, the description is minimally sufficient. It doesn't indicate ordering, result shape, or pagination limits, but none of that is strictly required given the annotations and simple 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 description coverage is 100% and the single param ('page') has a documented 'Zero-based page index.' description. The description merely repeats the default. Baseline 3 applies since the schema does the work.

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 resource (outgoing buy/escrow requests placed by the user) with a clear directional scope. The Arabic gloss '(وساطة)' and 'Buy with confidence' branding add texture, but it's clear this is a read of the user's own escrow requests. It does not explicitly differentiate from siblings, most of which are unrelated anyway.

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?

Implied usage as a listing of the current user's outgoing escrow requests, but no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. Adequate but with a clear gap.

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 readOnlyHint=true and idempotentHint=true, so the description should clarify it's a safe read. However, the description's format ('{...} for a post') resembles a mutation payload, which could confuse. It adds no behavioral context beyond what annotations provide.

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

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

The description is terse but poorly structured. The brace notation is confusing and the required parameter is tacked on at the end without clear separation. It lacks a clear statement of purpose.

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

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

For a tool with a single parameter and no output schema, the description should at least state what information it returns (contact details). Instead, it's ambiguous and provides no context about the tool's behavior or 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 description coverage is 100%; post_id is fully documented in the schema. The description lists related fields but since only post_id is a parameter, it adds minimal value beyond the schema. 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?

The description does not state what the tool does. It lists fields in braces and says '{contactText, contactMobile, shouldEnableWhatsApp} for a post' without a verb like 'get' or 'retrieve'. An agent cannot confidently determine the tool's action from this.

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 guidance on when to use this tool versus alternatives like get_post_details or comments. The description is purely a field listing.

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, so the safety profile is covered. The description adds value by enumerating the returned fields ({is_like, total, is_following}) in the absence of an output schema, but it does not clarify whose like status is returned or any auth requirements.

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 a single, front-loaded sentence with no filler, and the required parameter is flagged clearly. The telegraphic style borders on under-specification rather than excess, but nothing wasteful is present.

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-parameter read tool this is adequate: the return fields are enumerated despite there being no output schema, and the required input is stated. It still leaves the semantics of is_like/is_following (presumably relative to the authenticated user) unexplained, which a caller may need.

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 post_id parameter is fully documented in the schema as 'Haraj post id.', so the description's 'Required: post_id' adds nothing new. Baseline 3 applies when the schema already carries 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 names the resource (a post) and the data it exposes ({is_like, total, is_following}), so an agent can infer it reads like/engagement status. However, it never states a verb like 'get' or 'retrieve' and offers no differentiation from siblings such as comments or get_post_details, leaving the operation type to inference.

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

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

There is no when-to-use guidance at all: no indication of when this is preferable to get_post_details, comments, or other post-related siblings. The only usage-like content is a restatement of the required parameter, which does not tell the agent when to select this 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the return shape '{count, posts}', which is genuinely useful given no output schema. It says nothing about rate limits, auth, or pagination, so it is 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?

Three tight sentences, front-loaded with the verb and resource, no filler. The 'Required/Optional' clause mildly duplicates the schema, which prevents a 5.

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, describing the return payload is the right instinct and it is partially done. However, the description omits the third parameter 'full' and its effect on the return shape, which is the one piece of behavior an agent most needs for this fetch tool.

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

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

Schema description coverage is 100%, so both the Arabic tag/region semantics and the 'full' flag are already documented in the schema; baseline 3 applies. The description arguably goes backwards by implying the return is always '{count, posts}' when full=true yields full Post objects.

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 and resource: 'Fetch the promoted-post carousel for a tag.' That is concrete enough for an agent to know what comes back. It stops short of distinguishing itself from look-alike siblings such as fetch_feed or live_streams, which is the only thing keeping 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?

There is no statement of when to use this tool versus alternatives like fetch_feed or search. 'Required: tag. Optional: city.' only restates the schema's required/optional structure rather than giving selection guidance. An agent must infer the use case entirely.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), lowering the bar. The description adds real behavioral value by disclosing the return shape [{tag, count, city}] and the aggregate nature of the result, which the annotations cannot convey. It omits limits/pagination behavior, keeping it short of 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?

Two compact clauses plus a return-shape summary; every element (purpose, required/optional, output) earns its place and the intent is front-loaded.

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

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

With no output schema, the description appropriately supplies the return tuple, and required/optional params match the schema. It is nearly complete for a simple 2-param read tool, lacking only edge-case behavior such as what happens when a tag has no cities.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including Arabic examples for tag and city. The description's 'Required: tag. Optional: city.' largely restates the schema, so baseline 3 is appropriate; no additional format or syntax meaning is added.

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 resource and scope ('cities-with-counts for a given tag') and clarifies the concrete purpose ('powers the city-filter chips on tag pages'). This is distinguishable from siblings like trending_keywords or search_suggest, though it never names an alternative tool.

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

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

Implies when to use it via 'powers the city-filter chips on tag pages', giving an agent a contextual cue. However there is no explicit when-not guidance or naming of alternative tools for tag/city aggregation, so 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 this as a safe, read-only, idempotent, open-world read. The description adds material context beyond that: the compact-vs-full return mode and the exact return envelope ({keyword, count, has_next_page, view_options, posts}), which tells the agent what to expect back. It still omits pagination semantics (page/count interaction) and rate-limit 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?

Front-loads the purpose well and stays compact, but then enumerates all 14 parameters with their defaults, which duplicates a schema that already carries 100% description coverage. That parameter dump is largely non-earning text where a pointer to the schema would have sufficed.

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

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

For a tool with 14 parameters, no output schema, and no enum declarations, the description supplies the missing return shape and confirms default behaviors, which is enough for an agent to call it correctly. Minor gaps remain around pagination/has_next_page semantics and relative ordering when order_by_post_id is false.

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 parameters are already fully documented by the schema, including defaults, ranges (limit 1-100), and the during_date and near formats. The description largely restates those same parameters and formats, adding no new semantics, so the 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 ('Search haraj by keyword') and enumerates the filterable dimensions, so an agent immediately knows this is the keyword-driven post search. It does not, however, distinguish itself from siblings like search_suggest or trending_keywords, which also touch search/query concepts.

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 the required/optional split and the parameter list, but there is no explicit when-to-use guidance, no exclusions, and no reference to alternative tools such as search_suggest for query discovery or fetch_feed for browsing. An agent must infer context from the schema alone.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds a genuine behavioral trait beyond that: the result is capped at the top 10 suggestions, which tells the agent to expect a bounded, ranked list. It doesn't mention rate limits or auth needs, keeping it below 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 zero filler; the core purpose leads and the parameter summary follows. Every sentence earns its place.

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

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

For a simple two-parameter, read-only lookup with full schema coverage and no output schema, the description supplies enough: what it returns (top 10), scoping (prefix, optional tag), and the safe-read nature via annotations. Only the absence of guidance against sibling tools keeps it from 5.

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% — both `prefix` and `tag` are documented in the schema with the same Arabic example ('شاشة') the description repeats. The description therefore adds no meaning beyond what the schema already provides, which is the baseline-3 case.

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: 'Live search-box autocomplete' that 'Returns the top 10 suggestions for a typed prefix.' That is unambiguous. It does not, however, distinguish itself from siblings such as search, trending_keywords, or related_tags, 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?

'Live search-box autocomplete' implies the usage context (as-you-type prefix matching) but never states when to prefer this over the sibling `search` tool or when it is inappropriate. Usage is inferable, not explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds only the 'Arabic tag names' input constraint and the domain hint, but says nothing about result volume, pagination behavior, or the open-world data source.

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 resource and scoping key, then the required-input fact. No filler, though the domain parenthetical is somewhat ambiguous about which repository of sellers it refers to.

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 ideally would hint at what a 'sellers' result contains and how paging works. It supplies the input constraint and usage domain but leaves the return shape and pagination semantics unstated, so it is adequate but incomplete.

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%: the page parameter is documented as a zero-based index and tags as a list of Arabic tag names. The description merely restates the required tags argument, adding no format, limits, or semantics 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?

"Sellers for a tag" names the resource and its scoping key, which lets an agent infer it lists sellers associated with a given tag. However it is a noun fragment with no explicit verb and no comparison to related tools such as related_tags or user, so the boundary is only weakly drawn.

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 '(used by real-estate / business / investment pages)' gestures at context but never states when to call this tool versus alternatives, nor any prerequisites or exclusions. An agent gets no 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description usefully adds the return payload shape ([{keyword, score}]) and the default window, which matters because there is no output schema, but it says nothing about volume, rate limits, or ordering guarantees.

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 scope, then the parameter note, then the return shape. Efficient, though the parenthetical default duplicates the schema and could be dropped.

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 tool with full annotation coverage, the description supplies the one thing structured fields don't: the return shape. Nothing critical for correct invocation appears to be 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 sole parameter is fully documented in the schema, including its default. The description merely repeats the default value and adds no format, range, or semantics beyond it, 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?

States a specific resource (top trending search terms) and scope (last N days), which distinguishes it from near-neighbors like search_suggest and related_tags. It stops short of explicitly naming a sibling it replaces, so it lands just below the top band.

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 is given, and no alternative tool is named. An agent must infer that this is the discovery/trending path rather than the query-suggestion path (search_suggest) purely from the wording.

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 openWorldHint, so the agent knows this is a safe, repeatable read. The description adds the notable behavioral detail that rating_summary_only defaults to false and returns just the rating block, but doesn't disclose auth requirements, rate limits, or whether the profile is public/private. With annotations covering safety, a 3 is appropriate.

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

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

Three compact sentences, front-loaded with what the tool returns, followed by parameter guidance and the summary flag behavior. No wasted words, though the parenthetical badge list 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 read-only profile retrieval tool with 100% schema coverage and annotations carrying safety, the description is complete enough. It covers what is returned, how to identify the user, and a key output mode. Missing only edge-case behavior like errors for nonexistent users, but that is minor.

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 schema already documents all three parameters in detail. The description reinforces the username/user_id alternative and the rating_summary_only behavior, but adds no syntax or format details beyond the schema. Baseline 3 is correct 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?

States a specific resource (full user profile) and enumerates its contents (rating, followers, location history, badges), which is a clear verb-less but content-rich purpose. It doesn't explicitly distinguish itself from siblings like is_following_user or user_mention_suggestions, but the 'full profile' framing implies retrieval.

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 says to pass either username or user_id, which is genuine usage guidance, but it doesn't say when to use this tool versus alternatives like is_following_user or user_mention_suggestions. Usage is implied for profile retrieval but no exclusions or alternative routing is provided.

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 full safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's contribution is the result shape and the recency scoping implied by "recent." It does not disclose count, pagination, or the source of "recent," so it adds only modest context beyond the 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?

Two short sentences with zero filler; the purpose is front-loaded before the return shape. 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?

With no parameters and no output schema, the description supplies the essential return shape it needs to. It is nearly complete, though it leaves the recency window and result count unstated.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. The result-shape note is a bonus rather than compensation for a 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?

The description names a specific resource (@-mention candidates) and scopes it to the comment/DM composer, making the intent clear without opening the schema. It does not explicitly contrast with nearby siblings like search_suggest or user, so it stops short of full disambiguation.

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?

Embedding it as "for the comment / DM composer" implies the calling context, but there is no explicit when-to-use or when-not-to-use guidance versus alternatives such as user or search_suggest. Usage is only inferable.

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