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

Beyond the readOnly/idempotent annotations, it discloses performance behavior (about 3 s, up to 30 s on 100+ bid projects) and the operational response to it (keep limit small, page through). It also states the currency unit (Toman), which is not inferable from any structured field.

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

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

Three tight sentences, front-loaded with what you get, then why to call it, then the performance caveat. Every sentence carries information the schema and annotations do not.

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 and names the returned fields and their cross-reference (bidder names link to pn_profile). Combined with the latency warning and unit disclosure, an agent has everything needed to call this correctly and interpret results.

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

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

Schema coverage is 100%, so the schema already defines all three parameters; the description adds real guidance by tying `limit` to the slow-response constraint and directing paging via `page`. It doesn't clarify the page/limit interaction at max values, so it sits just above baseline rather than at the top.

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: 'List the offers freelancers made on a Ponisha project,' and enumerates the returned fields (price, days, pitch, bidder track record). This is clearly distinguishable from siblings like pn_project (project detail) and pn_search_projects (finding 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?

Gives two concrete use cases: 'see the competition on a project before bidding' and 'compare bidders.' It also routes the agent to pn_profile for bidder detail rather than doing that work here. It stops short of explicit when-not-to-use guidance or naming a competing sibling outright.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description's remaining behavioral value is the caveat that sub-categories are 'for reference' only, which is genuinely useful but thin; it says nothing about return shape or ordering.

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 leads in the first sentence, with the downstream-use tip immediately after; no filler. The final sentence about with_counts is slightly tacked on and duplicates the schema's own description of that flag.

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

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

A read-only enumeration tool with full schema coverage and no output schema; the description covers both modes and the downstream purpose. It would be stronger if it noted that each entry returns a slug and display name, since obtaining the slug value is the stated goal.

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

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

Schema coverage is 100% and both parameters are documented there, including the '14 searches' cost note for with_counts, so the baseline is 3. The description reinforces the semantic intent (top-level vs sub-category listing) but adds no 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 (list top-level project categories) plus the alternate mode (sub-categories of one), and explicitly names the sibling tools it feeds (pn_search_projects, pn_search_freelancers). An agent can tell this is the taxonomy-lookup tool rather than a search 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?

Provides explicit usage guidance: 'Use to get the `category` value for pn_search_projects and pn_search_freelancers', and clarifies that only top-level slugs are valid for those calls. No explicit when-not-to-use statement, but the intended 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?

The description adds critical methodology not found in the annotations or schema. It specifies the data scope ('50 newest open projects'), the measurement currency ('Toman'), and the aggregation type ('medians'), providing deep behavioral context about how the summary is constructed.

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 extremely concise, front-loading the purpose in the first sentence and immediately following up with clear, practical use cases. There is no wasted space and every clause serves a functional role.

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

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

Given that the input is minimal (a single skill name), the description provides maximal context by detailing the data sources, metrics (Toman/medians), and specific application scenarios, leaving nothing necessary for correct invocation or user expectation management 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?

With 100% schema description coverage, the parameter 'skill' is fully defined by the schema. The description adds minor semantic reinforcement ('for one skill') but does not elaborate on the parameter's function beyond what is already provided by the structured fields. Baseline score 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 clearly identifies the tool's function: to summarize demand and supply for a specific skill. It distinguishes itself from simple project searches (like pn_search_projects) by providing a synthesis of multiple market indicators.

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 explicit use cases, guiding the agent to use the tool when the user asks questions related to viability ('is it worth bidding on X'), pay levels, or market competition ('how crowded is X'). This high degree of scenario mapping reduces ambiguity.

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 annotations, the description discloses the approximate corpus size, ranking by Ponisha's quality score, the fields returned in search mode, and the reduced title-and-link output in username mode. This is substantial behavioral context that helps an agent predict results and avoid surprises.

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 three tight sentences: purpose first, usage second, and mode behavior plus next step last. Every sentence adds useful information with no repetition or 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 six-parameter search/list tool without an output schema, the description covers both modes, ranking behavior, returned fields, and a relevant follow-up tool. Pagination is left to the schema, and nothing essential for invocation is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds useful cross-parameter semantics: username overrides query and skills, and category applies only in search mode, which goes beyond the individual schema descriptions.

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

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

The description gives a specific verb and resource: search portfolio items or list one user's portfolio. It also distinguishes the two operating modes and points to pn_profile for the author, so an 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?

It clearly states when to use the tool: to see examples of work or inspect what a freelancer has built. It also explains the username mode and that query/skills are ignored there, but it does not explicitly contrast the tool with closer siblings such as pn_services or pn_user_projects.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing the returned facets (completed projects, rating, response rate, member since, last seen) and by drawing a hard scope boundary — private data such as contact and real name is not available. It does not cover error behavior for invalid or missing usernames, which keeps it below 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 short paragraphs, front-loaded with the core purpose, then usage, payload, follow-ups and the privacy caveat. Every sentence carries distinct information; 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?

With no output schema, the description compensates by enumerating what the profile contains and what include_resume toggles, plus the privacy exclusion. For a two-parameter read-only lookup, an agent has everything needed to select and 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 both parameters are already fully documented, including the pattern for username and the default for include_resume. The description's notes on include_resume ('adds their work history') largely restate the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a public Ponisha profile') and immediately scopes it to freelancer or employer, then enumerates the payload (level, skills, statistics, rating, activity). This is clearly distinguishable from sibling tools like pn_reviews or pn_user_projects, which surface only one slice of the same entity.

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 tells the agent where the required argument comes from ('a username from pn_search_freelancers, pn_bids or pn_project') and what to call next ('pn_reviews, pn_portfolios, pn_user_projects'). That is concrete routing in both directions, leaving little 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description instead adds real operational context. It warns that include_bid_sample can take up to 30 s on bid-heavy projects and explains that finished projects expose accepted_price and done_by. Slightly short of a 5 only because it doesn't say what happens when the project_id is missing or invalid.

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 sequencing hint, then the less common option and sibling pointers. Dense but every clause carries information; the final sentence listing three siblings is the only slightly crowded part.

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 does a solid job describing return fields including the conditional accepted_price/done_by for finished projects. Employer-block contents are named, though their exact shape is left to discovery.

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 covers only 50% (project_id is documented, include_bid_sample is bare). The description compensates well: it defines include_bid_sample as price statistics over the first 20 offers and flags the latency cost, which the schema does not convey. Still leaves the default behavior/format of that sample implicit.

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 Ponisha project') and enumerates the returned payload: full description, budget, skills, deadline, employer track record. Distinguishes clearly from pn_search_projects, which returns many 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?

Gives explicit sequencing ('Use after pn_search_projects') and routes the agent to sibling tools by need: pn_bids for offers, pn_reviews for reviews, pn_user_projects for the employer's other projects. Conditions that select this tool versus alternatives are 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real substance: the skill mode is capped to the newest 2000 reviews, and the user mode returns a score summary with named sub-metrics (star counts, quality, communication, timeline, expertise, hire-again, success rate). That is exactly the return-shape and data-limit context annotations cannot express.

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: capability, constraint/use case, then next tools. Front-loaded with the verb and the mutually exclusive parameter rule before the rationale, so an agent can act after one sentence.

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?

Four optional parameters, no nested objects, no output schema — and the description covers the exclusivity rule, the return contents, the data-reachability ceiling, and the logical follow-up tools. Nothing an agent needs in order 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 baseline is 3; the description rises above it by explaining the mutual exclusivity of username and skill and by characterizing what each returns (user → score summary; skill → cross-employer sentiment in a field). Page and limit are left entirely to the schema, which is acceptable since they are self-documented.

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 ("Read the reviews employers wrote about a Ponisha user") and immediately names the two distinct modes: per-user reviews and per-skill recent reviews. No sibling tool covers reviews, and the dual-mode framing lets an agent pick the right call 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 an explicit hard constraint ("Give exactly one of username or skill"), a decision context for each mode (judge a freelancer before hiring / judge an employer before bidding), and routes onward with "Next: pn_profile, pn_project." That is when-to-use plus alternatives, leaving little 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, but the description adds real context beyond them: what a result card contains (score, average rating, review count), what 'rating' actually means (average employer score out of 5), and a negative capability disclosure ('The site has no city filter') that prevents a wasted geographic search. No pagination/limit behavior is restated, but that is fully in 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: purpose and facets first, then the routing to sibling tools, then the disambiguation note on rating and the missing city filter. Every sentence earns its place with no repetition of schema 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?

With 8 optional parameters, no output schema and full schema coverage, the description supplies what the structured fields cannot: what results look like and where to go for more depth. It does not mention the page/limit ceilings or result ordering edge cases, but those are adequately covered by the schema itself.

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 all eight parameters (including the sort enum, level enum, skills matching semantics and category slug sourcing) are already documented. The description adds only marginal semantics ('ranked by score' and the max-5 rating meaning), so baseline 3 applies.

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

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

States a specific verb ('Search') plus resource ('Ponisha freelancers') and enumerates the searchable facets (text, skills, category, level, portfolio) with the ranking rule ('ranked by score'). It also disambiguates from siblings by naming pn_profile, pn_reviews and pn_portfolios as the tools that carry the deeper detail this one does not.

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 to find who to hire or to see who leads a niche' gives concrete selection contexts, and the follow-up routing sentence implicitly tells the agent when another tool is the better call. It stops short of an explicit when-not (e.g. when to prefer pn_search_projects or pn_services), so not quite a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: budget filters are applied client-side to the fetched page because the site has none, and up to 50 projects per page are scanned. It doesn't mention rate limits or the returned card fields, keeping it below 5.

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

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

Three sentences, zero filler. Scope comes first, then use case and sibling routing, then the behavioral caveat — appropriately front-loaded and dense with actionable 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 9-param tool with no output schema, the description covers purpose, routing, and the trickiest behavioral trait (client-side budget filtering). It characterizes results only as 'compact cards' without indicating what fields they carry, which is the one remaining gap for a tool that returns data 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. The description goes beyond the schema by explaining the interaction between budget filters and pagination ('up to 50 projects per page are scanned'), which affects how an agent sets page/limit when filtering by budget — a semantic detail the schema does not convey.

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 Ponisha projects') and immediately names the filter dimensions (text, skills, category, status, budget), so an agent can distinguish this from pn_search_freelancers 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 an explicit use case ('find work to bid on or see what employers ask for') and names concrete follow-up alternatives: pn_project for the full brief, pn_bids for offers already made. The division of labor between search and detail tools 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?

The annotations already cover safety (readOnly, idempotent, non-destructive), so this is a lower bar. The description still adds real value beyond them: it enumerates the fields returned (price, delivery time, inclusions, requirements, add-ons), which matters because there is no output schema, and it discloses that prices are denominated in 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?

Two sentences, no filler. The payload (what the tool returns) is front-loaded, and the second sentence handles sequencing and units. Neither sentence is redundant with the other.

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 full annotations and full schema coverage, this is complete: the agent knows what it fetches, when to call it, what it gets back, and the currency unit. No output schema is needed because the returned fields are enumerated in prose.

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

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

Schema coverage is 100% and the single parameter already documents itself as 'Package id from pn_services.' The description adds no format, range, or provenance detail beyond that. Baseline 3 applies when the schema does 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?

The first sentence names a specific verb (Get), a specific resource (one Ponisha service package), and enumerates exactly what is covered: price, delivery time, inclusions, requirements, paid add-ons. The singular 'one' plus the sibling reference to pn_services makes it distinguishable from the list-level sibling 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 pn_services to compare what a fixed-price offer really delivers' gives an explicit sequencing rule and names the correct prior tool. It stops short of stating when not to use it (e.g., list-only overview) or any prerequisite for a valid service_id beyond the schema, so not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds genuinely non-obvious context: the catalog is small (~80 packages in a few categories) and prices are denominated in Toman, which shapes how an agent should interpret result counts and currency. It stops short of describing the returned item shape or whether filtering is exact or fuzzy.

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

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

Three short sentences, front-loaded with what the tool is, then when to use it, then routing. The trailing 'Next:' pointer is a compact way to encode sibling handoffs without prose overhead. Nothing repeats 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?

With eight optional filter parameters, no required args, and no output schema, the description covers purpose, scale, currency and next steps adequately for correct invocation. The gap is that it never says what a result entry contains or that pagination is bounded (page max 200, limit max 30) beyond what the schema states.

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 all eight parameters are already documented with defaults, ranges and the sort enum. The description adds only the 'Prices are Toman' framing, which the schema's min_price/max_price descriptions already state, so baseline 3 applies.

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

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

States a specific verb and resource ('Browse Ponisha's ready-made service packages') and immediately parenthesizes with concrete examples ('logo design or WordPress themes') that anchor what a package is. The contrast with 'posting a project' cleanly separates it from pn_search_projects and pn_project.

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 when-to-use condition ('buy a defined service at a known price instead of posting a project') and names the two follow-up tools by function ('pn_service for deliverables and add-ons, pn_profile for the seller'). The alternative path is spelled out rather than left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world lookup, so the safety profile is covered. The description adds useful non-annotation context: the corpus size (~700 tags) and the fact that results carry a slug or id intended for reuse elsewhere. It omits behavior on zero matches, which keeps it below 5.

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

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

Two sentences, no filler, and the purpose plus the workflow instruction are front-loaded. Every clause carries usable 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?

No output schema exists, and the description compensates by telling the agent the result contains a slug/id to feed into the `skills` filter. Minor gaps remain (no-match behavior, whether results are ranked), but nothing blocking for a small two-parameter 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% and both parameters are documented in the schema, including the Persian/English example and the limit bounds. The description adds only 'by name' and the scale figure, no format or matching-semantics detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Find Ponisha skills') plus scale ('about 700 tags') and the search axis ('by name'). It is distinguishable from most siblings, though it never contrasts itself with pn_categories, the other taxonomy lookup an agent could confuse it 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?

Explicitly says when to use it ('Use first when the user names a skill') and names three concrete downstream consumers (pn_search_projects, pn_search_freelancers, pn_market) along with how to pass the result. That is a complete when-and-how routing instruction.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes far beyond them: it discloses the sampling method (points pages of 50 projects spread across history), that all statuses are included, currency (Toman), and a hard coverage limit (newest 10000 projects reachable). These are non-obvious behaviors an agent could not infer 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?

Front-loaded with the core purpose, then method, then the sibling pointer — a sensible reading order with little filler. It is on the longer side, and the return-value list could be tightened, but every clause carries operational 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?

There is no output schema, and the description compensates by enumerating what each sample reports (period covered, posting rate per month, median budget, median bids). Combined with the sampling and reach limits, an agent has enough to decide whether the answer will be reliable.

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, but the description adds real meaning: it explains that `points` is how many historical moments are sampled, each covering 50 projects, and that `skill` must be a single skill from pn_skills. That clarifies the practical effect of `points` beyond its min/max bounds.

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 — how demand and budgets for one skill changed over time on Ponisha — and scopes it to a historical, sampled view rather than a live snapshot. This clearly separates it from pn_market, which the description explicitly names as the tool for today's numbers.

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 named use cases ("is demand for X growing", "what did X pay a year ago") and an explicit alternative for a different need (use pn_market for today's numbers). It also warns that it samples across the whole history including all statuses, so an agent knows what it is and is not getting.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds the role-dependent result semantics and the pn_project follow-up chain, but says nothing extra about pagination, result volume, or what an empty/invalid username yields 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 short sentences, front-loaded with what the tool returns, then usage, then the next-step pointer. No filler and no redundancy with 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?

With full schema coverage, annotations covering the safety profile, and no output schema, the description covers what matters: result meaning by role and where to go next. Minor gap: no mention of how paginated or bounded the listing is, and no signal about what an unknown username returns.

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 enum for status is documented in the schema ('finished = completed projects (default); open = still taking bids'), so the schema does the heavy lifting. The description only indirectly reinforces status meaning through the 'finished work' phrasing; 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?

Names a specific verb and resource ('List the projects a Ponisha user is attached to') and adds the key nuance that the result set differs by role: an employer's own projects vs a freelancer's finished work. It does not explicitly contrast with close siblings like pn_search_projects or pn_portfolios, so an agent must infer the difference.

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 ('check an employer's history (what they ask for, how many finish) or what a freelancer has delivered') and prescribes the follow-up step: 'Call pn_project with an id for the full brief and the accepted price.' No explicit when-not or exclusion against sibling search tools, which keeps it short of a 5.

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