ScrapeField

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

With no annotations, the description carries the full burden, and it does disclose two real behavioral facts: the status stays `pending` until approval, and the key is returned only once. It omits other important traits for a polling endpoint, such as whether an approved response can be re-fetched, expiry behavior, or any 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?

Two tight clauses with no filler, and the state progression (`pending` → `approved`) is front-loaded before the key-usage note. The telegraphic style is efficient, though slightly clipped.

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 does cover the meaningful return values (status, api_key). However, for a polling tool it leaves the operational flow undefined: how often to check, what to do while pending, and whether the one-time key can be recovered. 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% and the single `id` parameter is documented in the schema as the value sign_up returned. The description adds nothing further about the parameter, so the baseline of 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 names the two possible outcomes of the check (`pending`, `approved` with `api_key`), which lets an agent infer this polls the status of a prior sign_up. It never states the action in a verb+resource phrase of its own, relying on the name and title to establish that. Clear enough to act on, but sibling differentiation from sign_up is only 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?

The only usage sentence tells the agent what to do with the returned key (`Authorization: Bearer …`), not when to call this tool. There is no guidance on polling cadence after sign_up, when to stop calling, or how this relates to the sign_up sibling that produced the `id`.

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?

No annotations are provided, so the description carries the full burden, and it does add genuinely useful behavior beyond the schema: cost of 3 credits regardless of cache, and refund on failure. It stops short of disclosing auth/permission requirements or rate limits, which would matter for a data-fetching 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?

Three dense sentences, front-loaded with what is fetched and what is returned, then usage, then the input constraint and cost. No filler or repetition.

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 enumerates the returned fields, and pagination is covered by the schema's cursor/next_cursor documentation. Cost and refund behavior round it out; only auth/permission context 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%, so baseline is 3, but the description adds a cross-parameter constraint the schema does not express: exactly one of url or shortcode must be supplied (the schema has no oneOf/anyOf and marks nothing required). That is real meaning beyond the structured fields.

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 (comments on one Instagram post), and enumerates the exact fields returned (username, text, timestamp, like_count, reply_count, parent_id). This clearly separates it from siblings like get_instagram_post (the post itself) and get_linkedin_post_comments / get_tiktok_comments (other platforms).

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

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

Gives a concrete use case (social listening and campaign verification) and a hard input constraint (exactly one of url or shortcode). However, it does not name alternatives or state when-not-to-use, so an agent has no explicit routing signal against the many other Instagram/comment siblings.

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

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

With no annotations, the description carries the full burden and does well: it discloses the current outage state, that failed calls are not charged and refunded, that a demo path still answers, and a fixed 64-credit cost regardless of cache. What it omits is any permission/scope requirements and the concrete shape of returned posts beyond 'a full post'.

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 tight sentences with no filler, and the availability caveat is placed first so an agent sees it before planning a call. The outage notice consumes roughly half the text, which is defensible given it changes whether the call is worth making, but it does crowd out return-value 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?

For a four-parameter read tool with a fully documented schema and no output schema, the description covers the remaining unknowns an agent needs: cost, refund policy on failure, current service availability, caching economics, and the intended analytical use case. Nothing critical to a correct 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 description coverage is 100%, so the baseline is 3. The description only echoes the single-hashtag scope and the cached-or-not distinction that the `fresh` parameter already documents; it adds no format, boundary, or pagination detail beyond the schema.

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

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

States a specific verb and resource — 'Fetch recent posts carrying one hashtag' — and clarifies the payload shape ('each a full post'), which distinguishes it from the comment/profile siblings. It does not explicitly name get_instagram_posts as the non-hashtag alternative, so differentiation is inferable rather than stated.

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

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

'Use this for trend and campaign monitoring' gives a positive use case, but there is no when-not guidance and no named alternative among the many sibling tools (get_instagram_posts, search_instagram_accounts). The agent must infer that this is the hashtag-scoped path rather than the account-scoped one.

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

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

With no annotations, the description carries the full burden and does well: it discloses the credit cost (3 credits, cached or not) and the refund policy for failed calls, plus the `fresh` trial-credit restriction. It stops short of stating auth requirements or the caching window.

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

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

Two sentences, zero filler. The resource and return fields are front-loaded, followed by the input constraint and cost — the ordering an agent needs.

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

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

For a single-item fetch with no output schema and no annotations, the description covers purpose, inputs, returned fields, and cost. Minor gaps (auth/permission requirements, whether the cache has a staleness window) remain but are not blocking.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine constraint the schema does not express: `url` and `shortcode` are mutually exclusive and exactly one must be supplied, despite `required` being empty. That closes a real ambiguity in the schema.

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

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

States a specific verb and resource ('Fetch one Instagram post or Reel') and enumerates the returned fields (caption, media, username, timestamp, counts), so an agent knows exactly what it gets. The singular 'one post' implicitly distinguishes it from the plural get_instagram_posts sibling.

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

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

Explicitly constrains input to 'exactly one of `url` or `shortcode`', which is actionable guidance for invocation. It does not, however, name when to prefer this over get_instagram_posts or get_instagram_comments when the agent already has a URL.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the cost (3 credits, cached or not) and the refund-on-failure policy, but says nothing about auth requirements or other operational traits beyond cost.

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

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

Two sentences, front-loaded with the core action. The long enumeration of return fields is dense but earns its place since there is no output schema.

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

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

With no output schema and no annotations, the description carries most of the burden and handles it reasonably: it states the returned fields, the input constraint, and the cost/refund model. Pagination details are covered by the schema, so nothing critical 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%, so the baseline is 3. The description adds genuine value by stating the mutual-exclusivity rule between `username` and `url`, which is not expressed in the schema (neither is required and there is no oneOf constraint).

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

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

The description opens with a specific verb and resource: "Fetch recent posts and Reels by one Instagram account," and enumerates the returned fields. An agent can distinguish it from get_instagram_profile and get_instagram_comments, though it does not explicitly name the closest sibling (get_instagram_post for a single 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?

It gives an important usage constraint — "Give exactly one of `username` or `url`" — but offers no explicit when-to-use or when-not-to-use guidance and does not route the agent to alternative siblings like get_instagram_post or search_instagram_accounts.

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

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

With no annotations, the description carries the full burden and does well: it discloses cost (3 credits, cached or not), refund behavior on failure, and implies cache/fresh semantics. It omits auth requirements and rate limits, keeping it short of a 5, but the billing and refund disclosure is genuinely useful context.

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

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

Front-loaded with the verb and resource, then field list, usage, constraint, and pricing. Every sentence earns its place, though the long inline field enumeration is slightly dense and could be trimmed since the fields are essentially the return contract.

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 compensates by listing the returned fields, and with no annotations it covers pricing and refund behavior. A note on authentication or freshness trade-offs would make it fully self-sufficient, but it is complete enough to call 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%, so the baseline is 3, but the description adds a real semantic constraint the schema does not encode: exactly one of username or url must be supplied (schema shows no required fields and no oneOf). This is meaningful guidance beyond the field-level descriptions.

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

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

States a specific verb (Fetch) and resource (an Instagram account) and enumerates the returned fields, so the agent knows exactly what it gets back. The fetch-by-identity framing clearly distinguishes it from the search_instagram_accounts sibling, which discovers accounts rather than retrieving one.

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

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

Gives a concrete use context ('creator discovery and audience sizing') and the key selection constraint ('Give exactly one of username or url'). It stops short of naming alternatives such as search_instagram_accounts for when the identity is unknown, so no explicit 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?

With no annotations, the description carries the full burden, and it does substantial work: it discloses the returned payload's shape (post, author, counts, timestamp, `comment_url`), ordering and page size ('newest first, up to 100 a page, with `next_cursor`'), caching behavior, and cost/refund policy ('7 credits, cached or not; a failed call is refunded'). It still omits auth requirements, rate limits, and behavior for nonexistent or private profiles.

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 well-ordered paragraph: scope first, then per-type behavior, then payload, then pagination, then purpose, then input rule, then cost. Every sentence earns its place, though the credit/caching information is partially duplicated by the `fresh` parameter description.

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, unannotated tool with no output schema, the description compensates well by describing the return shape, pagination, and billing. The remaining gap is operational context an agent may need before calling: authentication requirements and failure modes other than credit refund.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds constraints the schema cannot express: the mutual exclusivity of `url` and `vanity_name` (required is empty, so the schema itself permits both or neither), and that `posted_within` only applies with `type=comments`. These are real, decision-relevant additions.

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 with an explicit scope: 'what one person did recently on other people's posts', split by `type=comments` vs `type=reactions`. This implicitly separates it from person-agnostic siblings like get_linkedin_post_comments and get_linkedin_post_reactions, which operate on a single post rather than a single person.

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

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

Gives a concrete use case ('sales signals: who a prospect engages with, and on what') and a hard input rule ('give exactly one of `url` or `vanity_name`'), which orients the agent well. It does not, however, name an alternative sibling or state when not to use it (e.g. use get_linkedin_post_comments when you already have the 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?

With no annotations, the description carries the burden and does real work: it discloses the cost (7 credits), that caching does not change the price, and that failed calls are refunded. It also characterizes the breadth of the response (per-country sightings, targeting). It still omits auth/permission requirements, which is the notable remaining gap.

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

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

Three tight clauses front-loaded with purpose, then the input constraint, then the cost/refund caveat. No filler and nothing buried, though the passive 'Costs 7 credits' sentence carries slightly off-topic pricing detail that is nonetheless useful.

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-record fetch with no output schema, the description covers purpose, input cardinality, cost and refund policy, and the shape of the return. The main omission is any note on prerequisites or on where ids come from, which leaves one inference to the agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine constraint the schema does not encode: the schema marks no parameters required, yet the description says exactly one of `id` or `url` must be supplied. That clarification is meaningful beyond the structured field.

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 ('Fetch') plus resource ('one ad') plus identifier modes, and it enumerates what comes back ('what linkedin/ads gives, and where it was seen, country by country, with its targeting'). It is clearly distinguishable from the sibling search_linkedin_ads, which finds ads rather than retrieving one.

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 constrains input ('Give exactly one of `${id}` or `${url}`') but never states when to reach for this tool versus search_linkedin_ads, nor how to obtain an id in the first place. Usage is only implied by the 'fetch one by id' framing.

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?

No annotations are provided, so the description must carry the burden, and it does disclose valuable operational context: cost (3 credits, cached or not) and refund on failure, plus an implicit caching model. It omits auth/permission requirements and error behavior, but the pricing and refund disclosure is real value beyond structured fields.

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

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

Three sentences, front-loaded with the resource and its payoff fields, followed by usage, then the identifier constraint, then cost. The twelve-field enumeration is heavy but earns its place because there is no output schema to describe the return shape.

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 annotations and no output schema, the description compensates well: it covers return fields, usage context, the one-of identifier rule, and pricing/refund behavior. It stops short of authentication requirements or failure-mode detail, but for a simple lookup tool it is nearly complete.

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

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

Schema coverage is 100% so the field descriptions already document url, fresh, and vanity_name. However, the description adds a constraint the schema does not enforce ('Give exactly one of url or vanity_name'), since the schema declares no required params and no mutual-exclusion rule. That genuine added meaning lifts it above 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 (Fetch) and resource (a LinkedIn company page) and enumerates the exact fields returned (name, tagline, description, industry, follower_count, etc.). The 'from its LinkedIn URL' framing clearly separates it from search_linkedin_companies and from people-oriented siblings like get_linkedin_company_people.

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

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

Gives a concrete usage scenario — 'enrich a company from its LinkedIn URL' — which tells the agent when this tool fits. It does not name alternatives or state when-not to use it (e.g., vs. search_linkedin_companies for keyword discovery), so it falls short of a full routing statement.

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

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

With no annotations, the description carries the full burden and does so well: it discloses pagination (25 per page), cache/fresh behavior, a flat 170-credit cost whether cached or not, and refunds on failed calls. It stops short of documenting auth requirements or rate limits, which is the only remaining gap.

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

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

Purpose is front-loaded and the returned fields, cost, and usage are packed densely into one paragraph. Some phrasing ('The same object, and price, as linkedin/people...') leans redundant against the earlier sentence, but 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?

With no output schema, the description fully compensates by describing the returned object field-by-field plus pagination, pricing, refund policy, and cache semantics. Nothing an agent needs to call this 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 coverage is 100%, so the parameters are already fully documented. The description only restates company_id provenance ('company_id in linkedin/company') and implies cursor-based paging, adding little beyond the schema, which justifies 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 ('Fetch the people who list a company as their employer') and enumerates the exact return shape (name, location, profile, roles with title, employer, company_id, start month). It also anchors itself to a sibling ('the same object as linkedin/people with source=sales_navigator'), so an agent can distinguish it from other LinkedIn endpoints 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?

Gives clear usage intent ('Use this to map a company's team or to find who to contact') and cross-references the equivalent linkedin/people call. It does not, however, spell out when-not-to-use it or contrast it against in-domain siblings like search_linkedin_people, leaving the routing choice partly inferential.

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

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

With no annotations, the description carries the full burden, and it discloses real operational behavior: a flat 7-credit cost whether cached or not, and refund on failure. It also states the exclusive-or input constraint. It does not cover auth requirements or what a failure actually looks like, so it is strong 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?

Three sentences, zero waste. The purpose and return shape come first, usage second, and the operational constraints (exclusive input, cost) last — a well front-loaded structure.

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

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

With no output schema and no annotations, the description compensates by describing the return shape ('a list of names and member counts') and the credit/refund model. The exclusivity rule for the identifier params is also covered. Missing auth/permission context keeps it from a 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%, so baseline is 3. The description goes beyond the schema by stating 'Give exactly one of url or vanity_name or company_id' — the schema lists zero required parameters, so this exclusivity rule is information the agent cannot get from the structured fields 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?

Specific verb + resource ('Fetch the counts on a company's People tab') followed by the exact facets returned (location, function, education, skills). The framing as aggregate counts distinguishes it from the sibling get_linkedin_company_people, which enumerates individuals, without needing to open either schema.

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

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

States clear use cases: 'size a team, or to see where a company hires.' That gives an agent solid context for when this is the right call, but it names no alternative tool and gives no exclusions, 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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses the exact credit cost (7, cached or not), that failed calls are refunded, that group posts are unavailable, and the mutual-exclusivity of the two identifiers — all non-obvious operational facts an agent needs before calling.

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

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

Three sentences, front-loaded with what is returned, then the limitation, then the input rule and cost. Efficient overall, though the long enumeration of returned fields could be tightened slightly.

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 with no output schema and no annotations, the description covers returned fields, input constraint, cost, refund policy and cache behavior. Minor gaps remain — e.g. how `members` is returned (count vs list) and any rate limits — but nothing critical for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a constraint the schema does not express: `url` and `id` are mutually exclusive and exactly one must be given (required array is empty, so the schema alone does not enforce this). It adds real semantic value for the identifier choice.

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 (one group) and enumerates the fields returned (name, members, description, rules, creation date, post visibility), letting an agent distinguish it from get_linkedin_posts or search_linkedin_groups 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?

Gives clear context: this is a single-group lookup requiring exactly one of `url` or `id`, and it flags that group posts are not yet available via linkedin/posts. It does not explicitly name the scenario where searching (search_linkedin_groups) is preferred, 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?

With no annotations, the description carries the full burden and delivers real operational facts the schema cannot: cost is 3 credits "cached or not", a failed call is refunded, and the cache can be bypassed via `fresh` though not on trial credits. It omits auth requirements and rate limiting, which is the remaining gap for a metered external API 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?

Front-loaded with the purpose and return payload, then input rules, then cost — a sensible priority order with no filler. It is a single dense paragraph rather than separated clauses, so the cost/cache details are slightly buried, but 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, so the description must enumerate return fields, and it does so in detail while noting which fields are only present "where the posting shows" them — honest about optionality. Cost, cache, and input exclusivity are all covered; only auth/rate-limit behavior is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint the schema does not express: `required` is empty, yet the tool demands "exactly one of `id` or `url`". That mutual-exclusivity rule is essential to invoking the tool correctly and is only in the prose. It adds nothing further about `fresh` beyond the schema text.

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 one LinkedIn job posting by its id or URL") and then enumerates exactly what comes back (title, company, location, employment_type, seniority_level, salary, full description). It also distinguishes itself from the list/search sibling by noting it returns "the fields linkedin/jobs leaves null" and pulls one posting, so an agent can separate it from the plural search tool 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?

Gives a clear triggering context ("Use it on the job_id of a search result") and an explicit input rule ("Give exactly one of `id` or `url`"). It does not name the sibling search tool by its exact name (`search_linkedin_jobs`) and gives no when-not-to-use case, 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?

With no annotations, the description carries the full burden and delivers real behavioral facts: repost_count and reactions-by-kind are null because the source gives totals only, the call costs 3 credits whether cached or not, and failed calls are refunded. It stops short of stating auth/permission requirements or error semantics, so it is strong but 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?

Four tightly packed sentences, front-loaded with the purpose, then return fields, the null caveat, sibling routing, and pricing. Every sentence carries a distinct fact with 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 single-fetch tool with no output schema and no annotations, the description compensates by enumerating returned fields, flagging the null fields, disclosing cost/refund, and routing comments/reactions elsewhere. Nothing an agent needs to invoke 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%, so both url and fresh are already well documented, and fresh's cache/trial behavior is spelled out in the schema. The description's 'cached or not' cost note adds only a sliver beyond the schema, so the baseline of 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?

Starts with a specific verb+resource+scope: 'Fetch one post by its URL.' It also enumerates the exact fields returned (text, images, author, published_at, reaction_count, comment_count), which lets an agent distinguish it from listing tools like get_linkedin_posts without opening schemas.

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?

Routes the agent to alternatives explicitly: 'Use linkedin/comments for its comments and linkedin/reactions for who reacted' (matching the get_linkedin_post_comments/get_linkedin_post_reactions siblings). This is clear usage context, but there is no explicit 'when not to use' or note on scope limits beyond the comment/reaction handoff.

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

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

With no annotations, the description carries the full burden and does well: it discloses page size (up to 100), credit cost (7, cached or not), refund on failure, caching behavior, and the fresh-flag caveat. These are exactly the operational traits an agent needs before invoking a paid 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?

Front-loaded with the action and return shape, then usage, then the param rule and cost. Dense but every sentence earns its place; the returned-field list is slightly long but informative.

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?

Despite having no output schema, the description explains the return fields, pagination (100 per page, cursor), the two query modes, and the cost/refund model. Nothing essential for a correct call 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%, so the baseline is 3, but the description adds a critical constraint not enforced by the schema (required is empty): 'Give exactly one of url or comment_url.' It also clarifies that url's returned comment `url` opens the post at that comment, adding meaning beyond the raw pattern.

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 (comments on one LinkedIn post), and enumerates the returned fields, distinguishing it clearly from siblings like get_linkedin_post_reactions and get_linkedin_posts. The agent can identify the tool 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?

Explains the two modes ('Give exactly one of url or comment_url' and 'With comment_url, the replies to one comment') and the use case ('see who engages with a post and what they say'). No explicit comparison against alternative siblings, but the invocation condition is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses pagination (100/page), credit cost (7, cached or not), and a refund on failure. The member-id/vanity_name caveat explains a non-obvious result shape. It omits auth requirements and rate limits, but the cost and refund disclosures are strong.

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

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

Front-loaded with the core action and return fields, then constraint, then cost. Dense but nearly every sentence earns its place; the member-id sentence is the one most likely to be skimmable, but it conveys non-obvious 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?

No output schema exists, so the description must describe returns, and it does (name, headline, link, reaction type), plus pagination and cost. It covers what an agent needs to call and interpret the tool, though field-level result details remain partly inferred.

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% (baseline 3), and the description adds meaning beyond the schema by stating the url/comment_url mutual exclusivity and the actor.url member-id behavior. That interpretive context elevates it above the schema-only 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 ('Fetch who reacted to one post') with the exact payload returned (name, headline, link, reaction type). This is easily distinguishable from get_linkedin_post_comments and get_linkedin_post 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?

Gives an explicit selection rule: 'Give exactly one of `url` or `comment_url`', and describes the two modes (post reactions vs one comment's reactions). It also routes to a sibling ('linkedin/profile takes it'). It does not name an alternative reactions tool or state exclusions, so it falls just short of the top tier.

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?

No annotations, so the description carries the full burden and does so well: it discloses credit cost (7, or 3 with company_url), that caching does not change price, that failed calls are refunded, and that `fresh` is blocked on trial credits. It also discloses differing return shapes for person vs company (counts null and cheaper for companies). Missing only reversibility-style notes, which are largely irrelevant for a read 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?

Front-loaded with purpose, then return fields, alternative routing, the exclusivity constraint, and pricing. Dense but each clause carries information; slightly heavy for a single paragraph but no clear padding.

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

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

With no output schema and no annotations, the description steps in to describe field-level returns for person and company calls, cost model, and the one-of parameter rule, which is what an agent needs. Pagination and freshness nuances live in the schema descriptions, so the combination is adequate.

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 baseline is 3, but the description adds genuine semantics the schema does not: the mutual-exclusivity of url/company_url/query and the price differential tied to company_url. Format/syntax details for parameters remain delegated 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 and resource ('Fetch recent posts by one person or company, or ... every public post with those words'), covering the dual get/search nature. It distinguishes itself from the sibling get_linkedin_post by explicitly routing there for per-post counts.

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

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

Gives a hard selection rule ('Give exactly one of `url` or `company_url` or `query`') and names the alternative tool (linkedin/post) with the condition that selects it (wanting counts on a single post). It does not cover when to use fresh/posted_within, but context is otherwise clear.

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

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

No annotations exist, so the description carries the full burden and does so well: it discloses credit pricing per detail level (11 / 7 / 33), that caching is bypassed via `fresh`, that a failed call is refunded, and that `with_email` performs mail-server verification of each address. This is exactly the operational context an agent cannot get from the schema.

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

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

Three sentences, front-loaded with the payload fields, then the email caveat, then the invocation rule and cost. Every clause earns its place and nothing is repeated from the schema verbatim.

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 4-parameter, no-output-schema tool this is complete: fields returned, the extra email behavior, mutual-exclusion of the locators, cache behavior, and full cost model are all present. An agent can call this correctly without further inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains what `detail=with_email` does beyond the enum label (whole profile plus a work-email search delivered in `emails`) and imposes the mutually-exclusive url/vanity_name rule. It does not restate the enum semantics for `full` versus `main` in as much depth as the schema does.

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 (LinkedIn profile), enumerates the returned fields (full_name, headline, experience, education, skills, etc.), and scopes it against the sibling family of get_linkedin_* tools by making clear this is the person-level profile fetch.

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

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

"Use this to enrich a person from their profile URL" plus "Give exactly one of `url` or `vanity_name`" gives clear context and an invocation constraint the schema itself does not enforce (both are optional). It stops short of naming a specific alternative such as search_linkedin_people for discovery versus enrichment.

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

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

With no annotations, the description carries full behavioral load and does so well: it discloses the credit cost, that cache does not change pricing, that failed calls are refunded, that fresh cache-skipping is unavailable on trial credits, and that popular_times is null when unavailable. This is rich, actionable context beyond the schema.

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

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

The description is front-loaded with the core purpose and return fields, then moves efficiently through input rules, pricing, and cache behavior. The long field enumeration is justified by the absence of an output schema.

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

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

There is no output schema and no annotations, so the description must cover both return shape and behavior. It lists the returned fields, explains null handling, documents the input constraint, and states cost/cache/refund rules, leaving no critical gap for an agent calling the 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 already 100%, so the baseline would be 3. The description adds a key cross-parameter rule not enforced by the schema: exactly one of place_id or url must be supplied, and it explains that place_id may come from a search or Places API.

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 (Fetch), resource (one Google Maps listing), and scope (in full), then enumerates the returned fields so an agent knows exactly what comes back. It implicitly distinguishes this from sibling tools like get_place_photos, get_place_reviews, and search_places by promising the complete single-place record.

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 clarifies accepted identifiers (place_id or Google Maps URL) and says to provide exactly one, which tells the agent how to call the tool. However, it does not explicitly state when to choose get_place over get_place_reviews, get_place_photos, or search_places, leaving alternative selection to inference.

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

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

With no annotations, the description carries the behavioral load and does well: it discloses the return form (CDN URLs, not rehosted), the credit cost of 4, that caching does not change the price, and that failures are refunded. It omits auth/permission requirements and rate limits, so it is strong but 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?

Four tight clauses, front-loaded with the purpose, then output nature, then the identifier constraint, then cost/refund. Every sentence carries distinct information with no repetition of the schema.

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

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

For a 5-parameter, no-output-schema, no-annotation tool, the description covers purpose, return format, the critical identifier constraint, pricing, caching and refund behavior. Pagination and defaults are already handled by the schema, so nothing material 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%, so baseline is 3, but the description adds a real constraint the schema does not enforce: exactly one of `place_id` or `url` must be supplied even though the schema marks neither as required. It also characterizes the returned object (dimensions/uploader, nullable), which the schema does not cover.

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 photos on one place's listing') and immediately scopes it to one place, which cleanly separates it from siblings like get_place, get_place_posts and get_place_reviews. An agent can pick it 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?

Usage is implied by the resource name, and the description does impose the 'exactly one of place_id or url' rule, which is genuinely useful. However, it never names an alternative tool or states when NOT to use it (e.g. reviews vs posts vs photos), so routing guidance is only 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?

With no annotations, the description carries the full burden and does well: it discloses result ordering (newest first), billing behavior (4 credits whether cached or not), and a failure refund policy. It omits finer traits like pagination semantics beyond the schema's cursor and any rate-limit or auth notes, keeping it off a 5.

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

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

Three sentences, front-loaded with what is returned, then the use case, then the invocation constraint and cost. No filler and nothing repeated from structured fields beyond what is needed.

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, and the description compensates by describing the returned fields (text, day, image, link). Combined with the cost/refund notes and the exactly-one-of constraint, an agent has everything needed to call 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%, so 3 is the baseline and the schema already explains all four parameters. The description adds a constraint the schema does not encode (required is empty, no oneOf): "Give exactly one of `place_id` or `url`," which materially guides invocation.

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: fetching updates the owner posted on a single place's listing, and enumerates the payload (text, day, image, link target like an offer or event). This is clearly separable from nearby siblings such as get_place, get_place_photos, and get_place_reviews, which cover place metadata, images, and user reviews rather than owner announcements.

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

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

"Use this to watch what a competitor announces" gives a concrete use context, which is more than most siblings provide. It does not name an alternative tool or state when NOT to use it (e.g., vs. get_place or get_place_reviews), so it stops short of the explicit when/when-not/alternatives bar.

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

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

With no annotations provided, the description carries the full burden and delivers real operational context: cost (6 credits, cached or not), failure refund policy, caching semantics, and non-obvious pagination behavior (first page up to 8 reviews, later pages up to 20). It omits auth/permission requirements and any error modes beyond refunds, so it is strong but 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?

Three dense sentences: return payload first, then usage and the place_id/url rule, then cost/pagination mechanics. Every sentence carries information an agent needs, with no repetition of name or title.

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 enumerating returned fields is necessary and done. Cost, refund, pagination page sizes and the either/or parameter rule are all covered, leaving nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds a constraint the schema cannot express - that exactly one of place_id or url must be supplied (both are optional in the schema with no required fields). That mutual-exclusion rule materially improves correct invocation.

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 Google reviews for one place') and enumerates the returned fields (rating, text, language, publish_time, author badge, photos, owner_response). This clearly distinguishes it from siblings like get_place, get_place_photos and get_place_posts without the agent needing to open another 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 use case ('review monitoring and sentiment work') and the key selection constraint ('Give exactly one of place_id or url'). It does not, however, name a sibling alternative or state when NOT to use it versus get_place/get_place_photos, 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?

No annotations are provided, so the description carries the full burden, and it does disclose real operational traits: a 3-credit cost regardless of cache hits and a refund on failure, plus the parent_comment_id linkage for replies. It stays silent on rate limiting, auth requirements, or result ordering, 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?

Three tight sentences: purpose and payload first, the input constraint second, cost/refund last. Nothing is redundant with the schema and no sentence is padding.

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

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

With no output schema, the description usefully enumerates the returned fields, and pagination/refresh semantics are covered by the schema's limit/cursor/fresh descriptions. Only minor gaps remain (ordering of comments, whether replies are always included, applicability of the cache to cursor pages).

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 per-parameter baselines are already documented and a 3 would be the floor. The description adds a genuine cross-field rule ('exactly one of url or id') that the schema's empty required list does not express, so it earns above 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 precise verb+resource ('Fetch comments on one TikTok video') and enumerates the returned fields (username, text, create_time, like_count, reply_count, parent_comment_id), which unambiguously separates it from get_tiktok_video, get_tiktok_videos and get_x_replies. An agent can pick this tool 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?

The description implicitly defines when to use it (when you have a specific TikTok video and want its comments) and adds the useful constraint 'Give exactly one of `url` or `id`'. However, it never names an alternative tool or states when NOT to use it, e.g. for bulk comment harvesting via search_tiktok, so usage guidance 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?

With no annotations, the description carries the burden well: it discloses ordering ('newest first'), page size ('about 50 a page'), billing ('costs 3 credits, cached or not'), and failure handling ('a failed call is refunded'). It omits auth requirements and rate limiting, which are the main remaining behavioral unknowns.

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

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

Three dense sentences, front-loaded with the action and mode switch, then usage, then invocation constraint and cost. No filler or restatement of the title.

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 must describe the return shape, and it does ('each a profile with its follower and video counts'), along with ordering, pagination size, cursor propagation, and cost/refund behavior. Nothing essential for a correct call 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%, so the baseline is 3, and the description adds real value on top: the exclusive-or rule between `username` and `url` is not expressed anywhere in the schema (both are optional, no oneOf), and the `type` behavior plus page-size/pagination context clarify `cursor` usage.

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

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

Names a specific verb and resource ('Fetch an account's followers'), covers both modes via `type=following`, and disambiguates from siblings like get_tiktok_profile or get_x_followers by stating the exact returned entity (profiles with follower and video counts). An agent can distinguish it from search_tiktok and the other TikTok 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?

Gives concrete use cases ('see who an audience is, or who a creator watches') and an invocation constraint ('Give exactly one of `username` or `url`'). It stops short of naming alternatives or when-not-to-use conditions, so it is clear context without explicit routing.

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

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

With no annotations, the description carries the full burden and does well: it discloses the credit cost (3 credits regardless of cache), the refund policy for failed calls, and caching behavior tied to `fresh`. It omits auth/permission requirements and rate limits, but cost and failure semantics are disclosed where the schema alone would leave them hidden.

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

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

Three sentences, front-loaded with the resource and its return fields, followed by usage, constraint, and cost. The field enumeration is long but earns its place given there is no output schema; no filler sentences are 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 3-parameter, non-nested tool with no annotations and no output schema, the description covers returned fields, the input-exclusivity rule, usage intent, and cost/refund behavior. Only auth/prerequisite information is absent, a minor gap for a read-only profile lookup.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by stating the cross-parameter rule "exactly one of `username` or `url`", which the schema does not express (required is empty and there is no oneOf). It also notes the fields are "named as in TikTok's own APIs", clarifying the naming convention of returned data.

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 a TikTok account) and enumerates the exact fields returned, so the agent knows precisely what it gets. It is clearly distinguishable from siblings like get_tiktok_video, get_tiktok_followers, and get_tiktok_comments, which each target a different TikTok resource.

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

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

"Use this for creator discovery and audience sizing" gives concrete intent, and "Give exactly one of `username` or `url`" supplies the selection rule between the two input modes. It does not name an alternative tool (e.g., search_tiktok for finding accounts you don't yet know), so it stops short of full when-not/when-else 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?

With no annotations, the description carries the full burden and does well: it discloses the one-page limit, the volatility between calls, the 3-credit cost regardless of cache, and the refund on failed calls. It stops short of stating auth requirements 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?

Four short sentences, each front-loaded with a distinct fact: purpose, pagination/volatility, use case, and cost. No filler; every sentence earns its place.

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

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

For a no-annotation, no-output-schema tool, it covers pagination, result volatility, and cost/refund, and 'each a full video' hints at the return shape. Only auth/permission requirements are left unaddressed.

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

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

Schema description coverage is 100% and both parameters (fresh, region) are fully documented in the schema, so the baseline is 3. The description's mention of caching loosely relates to 'fresh' but adds no syntax or semantics beyond what the schema already states.

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), resource (trending feed videos), and scope (one country, now), plus the differentiating trait 'each a full video'. This clearly separates it from siblings like get_tiktok_videos and search_tiktok, which are ordinary lookups rather than the trending feed.

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

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

'Use this to see what is spreading' gives a clear intended context for selection, and the note that results change call to call implicitly warns against treating it as a stable list. However, no explicit when-not guidance or named alternative (e.g. get_tiktok_videos for a specific account's uploads) 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?

With no annotations supplied, the description carries the full disclosure burden and does real work: it states the cost (3 credits, cached or not), the refund policy on failure, the cache-skipping option, and the trial-credit restriction. What it omits is auth/permission requirements and rate-limit behavior, which keeps 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 sentences, zero filler. The identifier rule and the cost/refund terms are each stated once and front-loaded after the core purpose, so an agent gets the essentials in the first read.

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 enumerating the returned fields is valuable and correctly present. Cost, caching and refund behavior are covered, and the 'exactly one of' rule closes the required-field gap. Only the absence of auth/prerequisite context keeps it from a 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 coverage is 100% and each parameter is documented, which would normally set the baseline at 3. However, the schema marks nothing as required (required: []), so the description's 'Give exactly one of `url` or `id`' supplies a mutual-exclusivity constraint the schema cannot express — genuine added meaning beyond the structured field.

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 one TikTok video') and enumerates the payload fields returned (description, username, create_time, duration, counts, sound, duet/stitch flags), so the agent immediately knows both the action and the shape of the result. It is cleanly distinguishable from the plural sibling get_tiktok_videos and from get_tiktok_comments.

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

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

It gives one hard operational rule ('Give exactly one of `url` or `id`') and pricing/cache context, but never says when to choose this tool over get_tiktok_videos or search_tiktok. Usage is implied by the singular 'one' framing rather than stated as an alternative-selection rule.

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

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

With no annotations, the description carries the disclosure burden and does well: it states the credit cost (3 credits, cached or not) and that failed calls are refunded, which an agent cannot infer elsewhere. Read-only nature and the cache-bypass behavior of `fresh` are only implied or relegated to the schema.

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

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

Two sentences with the core resource and return fields front-loaded, followed by the selection constraint and cost note. The long field enumeration is dense but each item helps the agent judge relevance.

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, listing the returned fields is the right compensation, and pagination is fully covered by the schema's cursor/limit descriptions. Cost and refund behavior round it out; only the relative positioning against get_tiktok_video/search_tiktok 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%, so the baseline is 3, but the description adds the mutual-exclusivity rule for `username` and `url` ('Give exactly one of'), which the schema does not encode. That is genuine added meaning beyond the parameter descriptions.

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

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

States a specific verb and resource ('Fetch recent videos by one TikTok account') and enumerates the returned fields, making clear this returns a collection rather than a single item. It does not explicitly name the sibling get_tiktok_video or search_tiktok, so the differentiation from those tools is left 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?

Usage is only implied: 'recent videos by one TikTok account' tells the agent the context, and 'Give exactly one of `username` or `url`' is a useful selection constraint absent from the schema. However, there is no explicit when-to-use vs. when-not, and no alternative tool is named.

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

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

With no annotations, the description carries the full burden and delivers notable behavioral detail: it costs 3 credits whether cached or not, and a failed call is refunded — genuinely useful for an agent budgeting calls. It omits authorization requirements and any caching/rate-limit nuance, 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?

Three tight sentences: purpose and returned fields first, then the related resource and the parameter constraint, then cost. Every sentence earns its place with no padding.

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

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

For a simple single-entity fetch with full schema coverage and no output schema, the description covers purpose, returned fields, the parameter constraint, the related posts path, and cost/refund behavior. Nothing essential to invoking 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 coverage is 100%, so the baseline is 3, but the description adds the important constraint 'Give exactly one of `url` or `id`' — a mutual-exclusion rule not expressed in the schema (required is empty, no oneOf). This is real added value over the schema.

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

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

States a specific verb and resource ('Fetch one community') and enumerates the returned fields (name, description, member_count, created_at, join_policy, rules, creator), making it unambiguous. It also names the complementary `x/posts` with `community_url` path, distinguishing community metadata from community posts.

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?

Clarifies the boundary: this tool returns the community, while `x/posts` with `community_url` returns its posts, and it instructs to give exactly one of `url` or `id`. It provides clear context but stops short of stating when this tool should be preferred over, or is a prerequisite for, other X tools.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious traits: page size (~70 per page), a flat 13-credit cost whether cached or not, and refunds on failure. It does not state authentication prerequisites or confirm the read-only nature explicitly, but the cost/refund disclosure is well beyond what structured fields 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?

Front-loaded with the core action and pagination/cost facts packed into two sentences with little waste. The first sentence is dense with stacked clauses, but 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 5-param, zero-required, no-output-schema tool with no annotations, the description covers mode selection, page size, cursor semantics indirectly, cost/refund behavior, and the shape of returned items (counts and bio). Nothing critical for correct 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 already 100%, so the baseline is 3, but the description adds value: it clarifies the mutual-exclusivity rule for `username`/`url` (neither is schema-required) and gives a concrete pagination quantity. It adds detail beyond the schema rather than restating 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 and resource (fetch an account's followers / the accounts it follows) and covers both modes via `type=following`. It is distinguishable from neighbors like get_x_profile (profile details), get_x_retweeters (post-level) and get_tiktok_followers (different platform).

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?

Offers a use case ("Use this to see who an audience is") and a hard invocation constraint ("Give exactly one of `username` or `url`"), which is genuinely useful given both params are optional in the schema. However, it never names an alternative or a when-not condition, 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?

With no annotations, the description carries the full burden and does a solid job: it discloses per-call pricing, that the price applies whether or not the result is cached, and that failed calls are refunded — financial behavior an agent cannot see in the schema. It stops short of permission/auth requirements or rate-limit behavior, but the cost/caching/refund disclosure is genuinely valuable beyond the structured fields.

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

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

Two sentences, zero filler. The returned-field inventory comes first, the invocation constraint and cost/refund note second — well front-loaded and 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?

There is no output schema, so the description's enumeration of returned fields is exactly what an agent needs to decide whether the call answers its question. Combined with the cost and refund disclosure, nothing material for correct 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%, so the baseline would be 3. The description earns above baseline by stating the mutual-exclusion rule ('exactly one of url or id'), which the schema itself does not encode — required is empty and there is no oneOf/anyOf constraint. It adds no redundant restatement of the id/url/fresh fields.

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), resource (one post), and enumerates the returned payload — text, author, created_at, public_metrics with views, media, hashtags/mentions, reply/quote parent. The singular 'one post' implicitly separates it from get_x_posts and search_x, and the retrieval key (URL or id) is given up front.

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 tells the agent to 'Give exactly one of `url` or `id`' and discloses cost (3 credits) plus refund behavior, which is useful operational context. However, it never states when to prefer this over get_x_posts, search_x, or get_x_replies — the choice among sibling read tools is left to be inferred from the name 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?

With no annotations, the description carries the full burden and does so well: it discloses page size (~20), cursor-based pagination, cache-vs-fresh behavior, credit cost (13, or 3 with community_url), and that failed calls are refunded. That is materially more behavioral context than a safety hint would give.

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

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

Front-loaded with the core action and its two modes, then pagination, then returned fields, then cost. Three dense sentences with no filler; even the credit/refund sentence earns its place for an agent deciding whether to call.

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 enumerates the returned shape (text, created_at, public_metrics, media, hashtags, mentions), and all five parameters are covered between schema and description. Cost, pagination, and input constraints are all present.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning beyond the schema by stating the mutual-exclusivity constraint on `username`/`url`/`community_url` (the schema has no required fields and no oneOf) and by mapping `next_cursor` to the `cursor` parameter.

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

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

States a specific verb+resource (fetch an account's newest posts / a community's latest posts) with scope qualifiers that separate it from get_x_post (single post), get_x_community, and search_x. An agent can route correctly 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 clear selection conditions: use `community_url` for a community's latest posts in one window, otherwise paginate an account's posts via `next_cursor`. It also states the exclusivity rule ('give exactly one of username or url or community_url'). It does not name sibling alternatives (get_x_post, search_x) for the single-post or search cases, so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden, and it does disclose real operational traits: a fixed 3-credit cost regardless of cache, and a refund on failure. It omits auth requirements, rate limits, and error mode distinctions, so it is strong 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?

Four compact clauses ordered as payload, usage, input constraint, then cost — front-loaded with what the caller gets. The dense em-dash field list is slightly run-on but 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 output schema, the description usefully enumerates the return fields and their X API v2 naming, and it covers cost/refund and the input constraint. Missing auth/prerequisite detail keeps it from 5, but nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule ("exactly one of username or url") that the schema does not encode — required is empty and there is no oneOf. That is genuine meaning beyond the structured fields.

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 an X account") and enumerates the returned fields (username, name, description, location, link, verified, created_at, public_metrics). It is clearly an account-level lookup rather than a post/follower call, but it never names or contrasts with the many get_x_* siblings, so it stops short of the 5 bar.

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

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

"Use this to size an account or enrich a handle" gives a clear selection context, and "Give exactly one of `username` or `url`" is an explicit input rule. There is no when-not guidance and no named alternative (e.g., search_x for discovery), so it is clear context without 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?

With no annotations, the description carries the full burden and does well: it discloses page size (~30), the credit cost (13, cached or not), the refund policy for failures, and that caching can be bypassed. It omits auth/permission requirements and rate-limit behavior, which keeps 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 tight sentences: the first front-loads the purpose and result shape, the second carries the mutually-exclusive-input rule and cost model. No filler text.

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

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

With no output schema, the description responsibly summarizes the reply object and its referenced_tweets field, and covers pagination context via the cursor semantics plus the per-page count. Cost and refund details round out what an agent needs before calling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine constraint absent from the schema: exactly one of url or id must be supplied (the schema marks neither required and defines no oneOf). That cross-parameter rule is real value beyond the structured fields.

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 replies to one post') and immediately describes the returned payload shape (author, text, likes, replies, referenced_tweets). This cleanly separates it from siblings like get_x_post (the post itself) and get_x_retweeters (who reposted).

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 by the purpose – there is no explicit statement of when to pick this over get_x_post, get_x_retweeters, or search_x for reply data. The instruction 'Give exactly one of url or id' is an input constraint rather than usage guidance. Adequate but leaves alternative selection to inference.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses page size (~20 per page), the credit cost (13, regardless of caching), and the refund policy on failure. It omits auth requirements, rate limits, and the total-count/result cap, so it stops short of fully covering the operation.

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: purpose and page size first, then the input constraint, then cost. Every clause carries information an agent needs, with no filler or repetition of the title.

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 4-param, no-output-schema read tool, the description covers what a caller needs: identity of the resource, pagination size, cursor-driven paging (via schema), cost, and the url/id rule. It lacks auth/rate-limit context and doesn't say what happens at the end of the list, keeping it just short of complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds something the schema does not enforce: the required mutual exclusivity of `url` and `id` (the schema marks neither required and has no oneOf). That clarification is genuine added meaning, though `fresh` and `cursor` semantics come entirely from 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 (fetch) and resource (accounts that reposted one post), and clarifies the terminology gap by noting X's API calls this "retweeted by". It is clearly distinguishable from siblings like get_x_replies, get_x_post, and get_x_followers.

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

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

The description gives an input constraint ("Give exactly one of url or id") but no guidance on when to choose this tool over adjacent ones such as get_x_replies or get_x_post, nor when retweeter data is the right target. Usage is implied by the name and purpose 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?

With no annotations, the description carries the full burden and does so: it discloses the cost (3 credits, cached or not), the refund policy for failures, that results come from a search index so no counts are available, and that only one page is returned. These are exactly the operational traits an agent needs before spending credits.

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 sentences, front-loaded with purpose then return shape, alternative tool, and cost. Slightly dense with colon-separated lists, but no sentence is filler.

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

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

There is no output schema, and the description compensates by describing the return fields and ordering. Combined with the pricing/refund and index-limitation notes, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema description coverage is 100% and each parameter (query, limit, fresh) is already documented in the schema, so the description adds no parameter-level syntax or defaults. Baseline 3 applies since 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 verb and resource ('Find Instagram accounts by a keyword') and immediately specifies the returned fields, ordering, and page scope. An agent can tell it apart from get_instagram_profile because the description says this is for when you lack a username.

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 usage condition ('Use this to find creators and brands when you do not have a username') and names the alternative path ('call instagram/profile with a username for the whole account'). There is no explicit when-not clause beyond that username condition, but the routing guidance is clear.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses cost (3 credits regardless of cache), that failed calls are refunded, page size (~25 a page), and the cache/fresh distinction. These are exactly the operational facts an agent needs before invoking a paid 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?

Front-loaded with the purpose, then the return shape, then the usage hint, then cost — a sensible order. The middle sentence is long and comma-heavy, but nearly every clause earns its place by describing retrievable fields.

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-param, no-output-schema tool, the description compensates by listing the returned fields (advertiser, format, headline, text, media, CTA, destination, run dates, impressions range, targeting) and the pagination mechanism via the schema's meta.next_cursor. Nothing material for a correct first call 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%, so the field-level meaning of each parameter is already documented; baseline would be 3. The description adds value beyond the schema by surfacing the exactly-one-of(advertiser | company_id | query) exclusivity rule, which the empty required array does not express.

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 the ads LinkedIn shows in its public Ad Library') and enumerates the searchable axes (advertiser, ad words, company id, country, date), which cleanly separates it from the sibling get_linkedin_ad and search_tiktok_ads. It also previews the returned record, so an agent knows what it is buying before 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?

'Use this to watch what a competitor advertises' supplies a concrete use case, and 'Give exactly one of advertiser or company_id or query' is a hard selection rule the agent must obey. It does not explicitly contrast itself with get_linkedin_ad or state when-not to use it, 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses the cost (7 credits, cached or not), that failures are refunded, the page size cap, and the result fields. Auth requirements and rate limits are not mentioned, 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?

Three front-loaded sentences, no filler — the find action and scope come first, then result fields, then cost. The middle sentence is dense but each clause (result fields, follow-up tools) earns its place.

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

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

With no output schema, the description helpfully enumerates returned fields and covers pagination and cost. It is complete for a search tool but omits any auth/permission context, which would matter for an agent on trial credits.

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 query, location, company_size, cursor and fresh are all documented in the schema. The description restates the searchable dimensions (name/keywords, place, size) but adds no syntax or format detail beyond the schema, which is the correct 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 (Find/search) and resource (companies), with scope qualifiers (by name or keywords, place and size) and page size. It explicitly distinguishes itself from sibling retrieval tools by naming 'linkedin/company gives the whole page' and 'linkedin/employees its people', so an agent can separate discovery from detail-fetch.

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 for use (finding companies before drilling into details) and it routes the agent to the right follow-up tools for the full page or people. It doesn't explicitly state when NOT to use it (e.g., use get_linkedin_company if you already have the id), so it stops short of a 5.

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

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

With no annotations, the description carries the burden and does well: it discloses the 7-credit cost (incurred whether cached or not) and that failed calls are refunded. It also discloses page size and return fields, though it omits auth requirements and the credit/pack nuance that only appears in the schema for `fresh`.

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 a colon-delimited field list; almost every clause carries information. Minor density cost from packing return fields, pagination, and billing into one run-on 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?

There is no output schema, so the description's enumeration of returned fields and page size is valuable, and the cost/refund note covers a key operational concern. Cursor-based pagination is handled by the schema, leaving little materially 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%, so query, fresh, and cursor are already fully documented. The description adds only the page size ('10 a page') and implies keyword semantics for query, which is the baseline expectation 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 verb (Find) and resource (LinkedIn groups) scoped by keywords, and enumerates the returned fields (name, URL, members, summary). It is clearly distinguishable from the sibling get_linkedin_group, which fetches a single group.

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 keyword-based search framing implies the use case (discovery vs. lookup), but there is no explicit when-to-use guidance and no mention of the alternative get_linkedin_group for single-group retrieval. Usage is inferable but not 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?

With no annotations, the description carries the burden and does so well: it states the 3-credit cost applies whether cached or not, that failed calls are refunded, and that certain return fields are intentionally null. It omits auth/pagination-exhaustion caveats for a 12-param search, but the cost/refund disclosure is genuinely useful.

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

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

Front-loaded with purpose, then return shape, null behavior, and cost in three tight sentences. No filler; every clause carries information an agent needs.

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

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

For a 12-param search with no output schema and no annotations, the description compensates by enumerating returned fields, flagging which are null, and disclosing cost/refund behavior. Nothing critical for correct 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 description coverage is 100%, so every parameter including sort, fresh, cursor, and enums is already documented in the schema. The description adds only the broad 'keyword and location, with LinkedIn's own filters' framing, which is consistent but not additive. 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?

Specific verb + resource (search LinkedIn job postings) plus scope (by keyword and location, with LinkedIn's own filters). It implicitly differentiates from get_linkedin_job by naming it for the detail-only fields, so an agent can route 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?

Clearly directs the agent to linkedin/job when employment_type, seniority_level, salary or description are needed, which is the primary usage decision for this family. It does not spell out when-not to use it (e.g. vs. other search endpoints) or prerequisites, but the context is unambiguous.

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

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

With no annotations, the description carries the full burden and delivers: it discloses that public search hides many results as 'LinkedIn Member', page sizes (10 vs 25), latency (~3s / ~5s / sometimes 25s), credit cost (7 / 170) with refunds on failure, and caching behavior. This is exactly the behavioral context an agent needs before spending credits.

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 what the tool finds, then layers source, paging, latency, requirements and cost. Every clause is substantive, though the density of parenthetical asides ('and now and then up to 25') makes it slightly run-on rather than crisp.

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

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

No output schema exists, yet the description covers result source, page size, cursor continuation and cost — most of what an agent needs. It stops short of describing the shape of returned fields (name, title, company, URL) or how 'LinkedIn Member' placeholders appear in results, which is the remaining gap for a paginated search 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 the baseline is 3, but the description adds meaning the schema does not: it states that at least one of query/first_name/last_name/title/current_company/past_company/school/location must be given (required is empty in the schema) and explains the default source's tradeoffs. It does not clarify cursor pagination semantics 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?

Opens with a specific verb+resource and scope: 'Find people by name, title, company, school or place.' That cleanly separates it from sibling searchers like search_linkedin_companies, search_linkedin_jobs and search_linkedin_services, which target different resources.

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

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

Gives clear routing context: when to pick source=public vs source=sales_navigator (coverage vs cost), the constraint that at least one filter must be supplied, and points to the profile-retrieval tool for full details. No explicit when-not/exclusion guidance, e.g. 'if you already have a profile URL, use get_linkedin_profile instead', which keeps it off a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses result content (person with headline and place), pagination size (10 a page), billing (7 credits regardless of cache), and the refund policy on failure. It omits auth/permission requirements and any rate-limit nuance.

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

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

Front-loaded with the core purpose, then the sibling differentiation, then result shape and cost. Three dense sentences, no filler, every clause carries informational weight.

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 describing the return (person, headline, place, page size) plus cost and refund behavior. Combined with the fully-documented schema, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents `query`, `location`, `cursor`, and `fresh`. The description's inline examples mirror the schema's own examples and add no new syntax or constraint detail, so baseline 3 is appropriate.

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

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

States a specific verb+resource+scope: people who list a service, filtered by service and place, with a concrete example ("web design" in "California"). It explicitly positions itself against the sibling `linkedin/people` (search_linkedin_people) by noting it surfaces people that tool hides, so an agent can distinguish the two.

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 contrast with `linkedin/people` implies when to reach for this search over the general people search (service-oriented, broader coverage). However, it never states an explicit when-to-use/when-not rule or names the sibling by its callable tool name, leaving some routing 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?

No annotations provided, so the description must carry the full behavioral burden. It does well: discloses cost (3 credits), that failed calls are refunded, the return shape (full listing fields), and that pagination exists via next_cursor. It doesn't mention rate limits, authentication needs, or that the 'fresh' parameter is unavailable on trial credits (that's in the schema, but the description could reinforce it). Missing some behavioral context for a 9-param, no-annotation 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?

Three tight sentences, front-loaded with purpose and scope, followed by return shape and pricing. Every sentence 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?

For a tool with no annotations and no output schema, the description is quite complete: it covers what the tool does, how to use it vs a sibling, what it returns, and cost/refund behavior. However, it doesn't mention pagination mechanics in detail (though the schema does), and doesn't cover authentication or rate limits. Given the richness of the schema, this is adequate but leaves minor 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%, so the schema already documents every parameter in detail. The description adds context about the return shape and references next_cursor, but provides no additional parameter meaning (e.g., how query interacts with lat/lng, how country/language bias works). Baseline 3 is appropriate when 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 verb (find) and resource (businesses and places on Google Maps) with the query mechanism. Explicitly distinguishes from sibling google-maps/place (now get_place) by noting 'use google-maps/place when you already have a place_id.' An agent can route correctly without opening either schema.

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

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

Gives a clear use case ('build a list of businesses in an area') and names when to use the alternative (google-maps/place with a place_id). Doesn't explicitly state when NOT to use this tool (e.g., when you already have a place_id you should use the other), though that is implied. Good routing guidance overall.

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

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

With no annotations, the description carries the behavioral burden well: it discloses credit cost (3, or 13 for hashtag), that cost applies whether cached or not, and that failures are refunded. It does not describe permission requirements or the shape of returned data, but the cost/refund disclosure is genuinely useful context beyond the schema.

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 core purpose before result modes and usage. Every sentence carries distinct information 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?

For a five-parameter tool with no output schema, the description covers purpose, result modes, usage context, and cost behavior; pagination semantics are handled by the cursor and limit schema descriptions. It is nearly complete, missing only a note on how results are ordered or returned.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantic value by mapping `type` values to their returned resources (user→accounts, hashtag→hashtags) and by tying a cost differential to that enum. It leaves `fresh`, `limit`, and `cursor` to the schema, which documents them adequately.

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 TikTok by keyword) and immediately clarifies the three result modes the single endpoint can produce. It separates itself from the surrounding get_tiktok_* tools by scoping its purpose to discovery when the target is unknown.

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

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

Explicitly says to use it for trend research and creator discovery 'when you do not already have a username,' which implicitly routes the agent to profile/listing tools when an identifier is known. It does not name a sibling or an exclusion by name, so it falls just short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and mostly does: 3 credits whether cached or not, failed calls refunded, cache-skipping behavior, and the Europe-only geographic limit. It does not state whether results are ever stale beyond the cache note, but the cost/refund/scope disclosures are substantive and non-obvious.

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

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

Front-loaded with the core action and corpus, then fields, then cost/scope. The field enumeration is long but each item is load-bearing since there is no output schema. No filler sentences.

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

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

Compensates for the absent output schema by listing the ad attributes returned and the page size, and covers cost, refunds, and region. Auth requirements and rate limits are not addressed, but for a keyword-search tool the agent has what it needs to call 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 query, cursor and fresh are already documented in the schema; baseline 3 applies. The description adds only marginal meaning, mainly "about 12 a page" which contextualizes the cursor, plus keyword-scoping for query.

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 TikTok's public Ad Library by keyword) and enumerates the ad fields returned, which distinguishes it cleanly from search_tiktok (organic videos) and search_linkedin_ads. An agent can tell exactly what corpus is being searched 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?

"Use this to watch what a brand or a category advertises" gives clear intended context, and the Europe-only scope narrows applicability. It stops short of naming an alternative (e.g. search_tiktok for organic content) or an explicit when-not-to-use condition, so it misses the top band.

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

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

With no annotations, the description carries the full burden and does well: it discloses result ordering (newest first), page size (~20), the 13-credit cost regardless of cache, and the refund policy on failure. It omits auth requirements and rate limits, but the pricing/refund/caching disclosures are genuinely valuable operational context.

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

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

Roughly four tight clauses that are front-loaded with the core behavior (search semantics, ordering, page size) before moving to modes, use case, and pricing. No filler sentences; each clause adds distinct 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 4-parameter search tool with no output schema, the description covers ordering, page size, operator syntax, mode switching, and cost/refund behavior, which is enough to call it correctly. The `cursor`/`fresh` semantics live in the schema, so the description need not repeat them, though a note on result shape would round it out.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by showing concrete X search-operator syntax (`from:nasa`, `since:2026-09-01`, `lang:en`) usable inside `query`, which the schema only gestures at with "X's search operators." It also reinforces the post/user meaning of `type`.

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

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

Specific verb+resource (search X, mirroring its own search box) plus scope qualifiers: newest-first ordering, ~20 per page, and the `type=user` switch for account search. An agent can tell this apart from get_x_posts/get_x_profile and from the other platform search_* siblings 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?

"Use this to follow a topic, a brand or a campaign" gives a concrete use context, and the `type=user` clause clarifies when to switch modes. No explicit when-not or named alternative sibling (e.g., vs get_x_posts for known accounts), so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the email-verification handshake, that the key is returned only once inside check_sign_up's answer, that `id` must stay secret, and that agent-started accounts get no free credits. It does not specify what happens on failure/expiry or any polling rate limit, so it is strong but 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?

Dense but front-loaded — the core ask comes first, then the flow, then the caveats. Every sentence carries information, though the sequence of constraints makes it slightly long for its size.

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

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

There is no output schema, so the description must supply the return contract, and it does: it explains that `user_code` is shown to the user and that `id` drives the polling, with the key arriving in check_sign_up's response. Only failure modes and timing guidance are left implicit.

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 `agent` and `email` are already fully documented in the schema; the description adds no further input-side meaning. Notably, the values it names (`user_code`, `id`) are outputs of this call, not input parameters, so they don't enrich 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?

States a specific action and resource: requesting a ScrapeField API key/account on behalf of the person the agent works for. It is clearly distinguishable from the data-fetching siblings and explicitly links to the check_sign_up sibling in the same flow.

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 gate ("Use this only when your person asked you to set ScrapeField up") plus the downstream procedure: show `user_code`, have the person check email, then poll `check_sign_up` with `id` until approved. The when-to-use and next-step alternative are both spelled out.

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