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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine value beyond them by revealing that only top-level categories are returned (not a full tree) and that the output feeds two specific consumers, `category_id` on kl_projects and `province` on kl_freelancers. It stops short of describing the response shape, such as whether categories and provinces come back as separate lists.

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

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

Two short sentences, no filler: the first names what is returned and its shape, the second routes the agent to the correct usage. The downstream consumer is named before the alternative use case, which is the right order.

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

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

For a zero-parameter read tool with rich annotations, the description supplies what the agent needs: scope (top-level only), the meaning of the two outputs, and which siblings consume them. Without an output schema, one more detail (e.g. that categories and provinces are returned together as separate collections) would close the remaining gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is a 4. The description correctly implies a parameterless enumeration rather than a filtered lookup.

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 ('List ... top-level categories ... and the provinces') and immediately ties the output to concrete downstream use (the ids kl_projects accepts as `category_id`). An agent can distinguish this from kl_skills or kl_services without opening any schema.

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

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

Explicitly names two use cases: browsing by category instead of keyword, and obtaining valid `province` values for kl_freelancers. That is real when-to-use guidance with a named alternative (keyword search), though there is no explicit when-not-to-use or prerequisite context.

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

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

Beyond the read-only, idempotent, open-world annotations, it identifies the profile as public and reviews as untrusted user content. The concrete instruction to quote reviews but not follow them adds valuable prompt-injection protection rather than merely restating annotation safety.

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

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

Two short paragraphs front-load the operation and returned content, then provide sequencing and review-handling guidance. Every sentence serves a distinct purpose, with no filler or redundant parameter 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 simple two-parameter read-only detail endpoint, the combined definition covers returned content, workflow position, ID sources, and review pagination. The untrusted-review caution supplies the key output-handling behavior, and the absence of an output schema leaves no material selection or invocation gap.

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

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

Schema coverage is 100%, with the schema documenting both valid ID sources and review pagination, including page size, ordering, default, and minimum. The description only indirectly reinforces the ID workflow, so the high-coverage 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 pairs a specific verb and resource—"Get a Karlancer freelancer's public profile"—with a concrete list of returned content, including bio, rating, skills, experience, and reviews. "Use after kl_freelancers" also helps distinguish this singular detail lookup from the sibling list tool.

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

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

It provides an explicit workflow cue: use this tool after kl_freelancers, implying that the agent should obtain an ID before fetching details. It does not give exclusions or mention kl_top_freelancers as another entry point in the description itself, although the ID schema does.

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

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

The annotations already establish that this is a read-only, idempotent, open-world, non-destructive call, so the safety profile needs no restating. The description adds only that results carry rating and skills information, and that returned ids feed kl_freelancer, while saying nothing about result volume, ranking behavior, or empty-result handling beyond what the schema covers.

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

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

Two short sentences with the capability stated first and the sibling hand-off second; no filler, and nothing an agent needs is buried. Every clause earns its place by either defining scope or directing follow-up.

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 six-parameter, all-optional search tool with rich schema descriptions and full annotation coverage, the description supplies purpose, use case, and next-step routing. The only gap is that result-set characteristics (24 per page, 10,000 match cap) live solely in the schema, so an agent reading only the description would not know result volume.

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

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

Schema description coverage is 100%, with every parameter documented in detail, including the 'best' vs 'newest' ordering and the Persian province format. The description names keyword, skill, and province at a high level, which simply mirrors the schema rather than adding new meaning, so the baseline 3 applies.

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

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

The description gives a concrete verb and resource ('Search Karlancer freelancers') plus the searchable dimensions (keyword, skill, province), so an agent knows exactly what it retrieves. It also distinguishes itself from the sibling kl_freelancer by naming that tool as the profile/reviews drill-down, making the boundary between the two clear.

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 find people to hire or to benchmark a skill's market' supplies concrete use cases, and the closing sentence routes the agent to kl_freelancer when it needs profile detail. It stops short of exclusions, such as when kl_top_freelancers or kl_market_rate would be the better pick, so it is strong but not fully exhaustive.

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

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

Beyond readOnly/idempotent annotations, the description discloses the computation method (sample of newest projects and best-ranked services), the caveat that Karlancer publishes no budget statistics, and that the figures are a guide rather than a market average. That is exactly the interpretive context an agent needs to avoid presenting the numbers as authoritative, and it adds the currency unit (Toman).

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

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

Purpose is front-loaded in the first sentence, followed by the use case and then the methodological caveat. Every sentence carries information; nothing is repeated from the schema or annotations.

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

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

With no output schema, the description steps in to say what is returned (budget spread, service prices, supply) and in what unit (Toman), plus how much to trust it. For a read-only estimation tool with four optional parameters this is 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 description coverage is 100%, so the schema already carries the meaning of query, skill, category_id and sample_pages. The description adds no further parameter detail, only the output-unit note (Toman), so the baseline 3 applies.

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

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

"Estimate what a skill pays on Karlancer: budget spread of recent projects, service prices and supply" gives a specific verb (estimate) plus the exact resources aggregated, which distinguishes it from listing siblings like kl_projects or kl_services. It never explicitly contrasts itself with near neighbours such as kl_trending_skills or kl_similar_projects, so sibling differentiation is inferred 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 'how much should I charge or pay for X'" gives a concrete triggering question, which is strong when-to-use guidance. There is no when-not guidance and no named alternative, though the schema's references to kl_skills and kl_categories implicitly route ID lookups elsewhere.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so safety is covered. The description adds genuine context beyond them by disclosing that bids and employer identity are not exposed, which tells the agent what it will not find and prevents wasted follow-up calls.

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

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

Two sentences, no filler, with the resource and its returned fields front-loaded before the workflow hint. Every clause adds information the agent needs.

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

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

With no output schema, the description usefully summarizes return content and notes the excluded fields, so an agent knows what it gets. Minor gaps remain around error behavior for an unresolvable project reference, but nothing essential to 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% and the parameter description already explains the token, slug, or URL forms, so the schema carries the semantics. The description only contributes the sequencing hint that the token comes from kl_projects, which is baseline-level added value.

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 ("Get one Karlancer project in full") and enumerates exactly what comes back: brief, budget, duration, hire deadline, skills, category path, city. That field list cleanly separates it from the list-oriented sibling kl_projects.

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 after kl_projects" gives an explicit prerequisite and implies the token provenance, which is the main routing decision an agent faces. It does not name a concrete alternative for related needs (e.g. kl_similar_projects for recommendations), so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered; the description adds genuinely new behavior: budgets are denominated in Toman, results carry a `token` that unlocks the detail call, and bid counts are deliberately absent from the public data. That last caveat prevents an agent from promising data that does not exist, though filter/pagination quirks are left 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 short paragraphs with the search scope front-loaded, then use cases, currency, the token hand-off, and the bid-count limitation. Every sentence carries information an agent would otherwise have to guess, and nothing is padded.

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

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

For a nine-parameter read-only search with full schema coverage and no output schema, the description plus schema covers what is needed to call it and to chain into kl_project. The only real gap is guidance on combining filters or interpreting result volumes, which the schema only partly addresses.

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 already carries a description, including the Toman unit and the per-page filtering caveat for low_competition. The description's 'keyword, skill, category and budget' phrasing and its Toman note largely restate what the schema documents, 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 gives a specific verb and resource ('Search open freelance projects on Karlancer') plus the filter axes (keyword, skill, category, budget), and explicitly distinguishes itself from kl_project by saying the token is what you pass to that sibling for the full brief. An agent can route between the list tool and the detail tool 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?

It states two concrete use cases ('find work to bid on' and 'see what employers ask for and pay') and prescribes the follow-up call to kl_project. It does not mention when to prefer kl_similar_projects, kl_market_rate, or kl_categories instead, so alternatives beyond the detail tool are left implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds value beyond them by disclosing the payload contents ("includes the price packages and buyer reviews"), which is meaningful because there is no output schema. It stops short of noting failure modes for an invalid token or slug.

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 capability, then a short routing paragraph - no filler sentences. The second paragraph leans toward cross-tool navigation rather than this tool's contract, but it is short and earns its space.

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

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

For a single-parameter read tool with strong annotations and no output schema, the description supplies everything needed: what comes back, how to obtain the identifier, and where to go for related data. No material gap remains 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 coverage is 100% and the schema itself explains that `service` accepts a kl_services token, a slug, or a karlancer.com URL. The description adds no syntax or format detail beyond that; its only parameter-adjacent content is guidance about passing the seller id to a different tool.

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?

"Get one Karlancer service in full" names a specific verb and resource, and enumerates the fields returned (description, price, delivery time, requirements, FAQ, skills, seller stats). The singular "one service" plus the sibling tool kl_services makes the list-vs-detail split unambiguous 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?

"Use after kl_services" states the explicit prerequisite and sequencing. It also routes adjacent needs elsewhere - kl_freelancer for the seller profile and kl_worksamples for the portfolio - so the agent knows which sibling covers what this tool does not.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful domain fact that these are fixed-price listings, but says nothing about result volume, pricing currency handling beyond what the schema states, or empty-result behavior. Against an already-complete annotation set, this is modest added value.

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

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

Two sentences with no filler: identity and scope first, usage and hand-off second. Every clause carries information the agent uses for selection or invocation.

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, seven optional parameters, and all parameters documented in the schema, the description supplies the missing domain framing and the follow-up path to kl_service. Slight gap: nothing describes what a result row contains or how to page through many results, which would matter for a 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 coverage is 100%, with per-parameter descriptions including page size, sort enum meaning, skill-id sourcing from kl_skills, and price units in Toman. The description only restates the keyword/skill/price axes already documented in the schema. Baseline 3 is appropriate 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 and resource ('Search Karlancer services') and defines the domain object in parentheses as ready-made fixed-price gigs, which an agent cannot infer from the name alone. It also distinguishes itself from kl_service by pointing to that tool for detail. It does not differentiate from other search-adjacent siblings such as kl_market_rate, which the 'what a task costs' framing overlaps with.

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

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

Gives two concrete use cases ('see what a task costs on the market' and 'compare sellers') and an explicit next step ('Pass a token to kl_service for details'), so the agent knows both when to enter and when to leave the tool. It stops short of stating when not to use it, notably versus kl_market_rate or kl_projects for cost-style queries.

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

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

The annotations already establish a read-only, idempotent, non-destructive open-world operation. The description adds that results are Karlancer-suggested rather than exhaustive and include budget and duration, but gives no information about result count, ordering, pagination, freshness, or empty results.

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 compact and front-loads the operation and notable result fields. The final sentence is short but somewhat misdirected because it explains how to invoke kl_project instead of explicitly completing this tool's invocation workflow.

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

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

For a simple one-parameter read-only tool, the purpose, workflow position, and key result attributes are enough for basic selection and invocation alongside the schema. It would be more complete if it explicitly connected the prerequisite kl_project call to the identifier supplied here and disclosed any result-limit behavior, particularly since there is no output schema.

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

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

The sole project parameter has 100% schema coverage, including its accepted token, slug, and URL forms, so the schema does the necessary work. The description mentions a token but attaches it to kl_project rather than clarifying this tool's project argument, adding little beyond the schema and potentially causing confusion.

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?

“List the projects Karlancer suggests as similar to one project” gives a specific verb, resource, and relationship, clearly distinguishing it from kl_project and kl_projects. Mentioning budget and duration further clarifies what the similar-project listings contain.

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 after kl_project” provides an explicit workflow position, while “to see comparable work and what else employers ask for” explains when the tool is useful. It does not discuss when not to use it or name an alternative for broader project discovery, and the closing instruction slightly muddies the workflow.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds that results include a per-skill freelancer profile count, which is return-value context not present in any structured field; it says nothing about pagination or result limits, keeping it short of a 5.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the integration guidance immediately after. 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 one-parameter lookup with no output schema, the description supplies what the tool returns (ids plus profile counts) and why an agent would call it (to populate filter arguments elsewhere). Nothing needed 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 coverage is 100% and the single `query` parameter is documented with partial-match semantics and Persian/English examples. The description's "by name" adds little beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ("Look up Karlancer skill ids by name") and adds scope ("with how many freelancer profiles list each skill"), which distinguishes it from siblings like kl_trending_skills or kl_categories that also surface skill data.

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

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

Explicitly states the use case: fetching ids that feed the `skills` filter of kl_projects, kl_freelancers and kl_services. That names the downstream consumers and tells an agent exactly when this lookup is a prerequisite rather than a standalone query.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds genuinely non-obvious context that this returns a curated, editorially featured subset rather than a query result, and that records include rating and skills. It stops short of saying how large the result set is or whether it is paginated.

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 first defines what the tool returns, the second handles tool selection. The purpose is front-loaded before the routing hint.

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

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

With no parameters and no output schema, the description carries the full burden of explaining return shape, and it does mention rating and skills per freelancer. The only omission is result-set size or ordering guarantees, a minor gap for a fixed zero-arg list.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level gaps exist.

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 ("List the freelancers") plus the exact scope: the curated top-rated set featured on the Karlancer home page, including rating and skills. That scope distinguishes it cleanly from the general kl_freelancers sibling without needing the schema.

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

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

Explicitly routes the agent: use this for "a quick view of the best-reviewed people" and use kl_freelancers "to filter." The condition that selects this tool over the alternative is stated outright, leaving nothing to inference.

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

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

Annotations already cover read-only/idempotent safety, and the description adds the non-obvious caveat that counts come from a 24-per-page sample of newest projects rather than the whole site – a real limitation an agent must know before trusting the numbers. It does not say anything about ordering or output shape, but no output schema exists and the sampling warning is the main behavioral risk.

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

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

Front-loads the core purpose in one sentence, then adds the sampling caveat and the follow-up hint. Every sentence carries information; only the odd mid-description line break slightly hurts readability.

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

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

For a zero-required-parameter read tool, the description covers purpose, the demand-snapshot interpretation, the sample-size caveat, and the suggested next call. The only gap is that it does not characterize the returned ranking (e.g., skills with frequency counts), which an agent must infer.

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 'top', 'pages', and 'category_id' are already documented in the schema, including the page size of 24. The description's mention of '24 per page' reinforces the 'pages' parameter's effect but adds no syntax or semantics beyond the schema, so the baseline applies.

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

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

States a concrete verb and resource ('show which skills employers ask for most') and scopes it to the newest projects. It is distinguishable from kl_skills (a plain skill list) by the demand/trend framing, though it never names that sibling directly.

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 ('see what is in demand right now') and a useful downstream workflow: pass a returned skill id to kl_projects or kl_market_rate. It does not say when to prefer kl_skills over this tool, so the alternative selection is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds useful value by naming exactly what comes back, but says nothing about rate limits, missing/invalid token behavior, or error cases for an open-world lookup.

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

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

Two sentences, zero waste, and the return contents are front-loaded before the workflow hints. 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 one-parameter read tool with no output schema, the description compensates well by enumerating the returned fields, and it closes the loop by naming the follow-up tool. Nothing essential to 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% and the schema already spells out that the parameter accepts a token from kl_worksamples, a slug, or a karlancer.com/worksample/... URL. The description adds no acceptance details of its own, so the schema is doing all the work.

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

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

States a specific verb and resource ('Get one Karlancer portfolio item in full') and enumerates the payload contents (description, skills, price range, duration, owner, similar items). It also implicitly contrasts with the plural sibling kl_worksamples, which returns the list this tool retrieves a single item from.

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 sequences the tool: 'Use after kl_worksamples' and then routes the agent onward with 'Pass the owner id to kl_freelancer for the profile.' That is strong workflow guidance with named alternatives, though it gives no conditions under which this tool should be skipped.

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

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

The annotations already declare this as a read-only, idempotent, non-destructive operation, so the description does not need to repeat safety details. It adds useful behavioral context by explaining that results are portfolio items and that a separate detail call is needed for full item information via the token. It does not describe pagination or result fields, but those are partly covered by 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 short, front-loaded, and waste-free. It states the primary capability first, then use cases, then the alternative detail tool in a single compact sentence. Nothing is repeated unnecessarily.

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

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

For a read-only search/list tool with rich schema coverage and annotations, the description gives enough context to select and invoke it correctly. It implies that results carry a token usable with kl_worksample, which partially compensates for the lack of an output schema. However, it does not explain result shape or pagination behavior, which leaves a small gap for agents unfamiliar with the API.

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 explains every parameter, including page, order, query, skills, and freelancer_id. The description adds only conceptual context, such as using freelancer_id to list one freelancer's portfolio. It does not add syntax or edge-case detail beyond what the schema already provides, 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?

The description names the specific resource (portfolio items / work samples on Karlancer) and the two main modes: searching broadly or listing one freelancer's portfolio. It also distinguishes this list/search tool from the sibling detail tool kl_worksample, so an agent can tell them apart without opening the 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?

It gives clear usage contexts: judging the quality and typical price of a skill's work, or vetting a freelancer. It also explicitly routes the agent to kl_worksample for full item details when a token is available. The main gap is that it does not explicitly exclude or compare against other sibling tools such as kl_freelancers or kl_service.

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