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

Annotations already declare read-only, idempotent, open-world and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: result ordering, approximate corpus size, and the shape of each row including the null-rating-without-reviews caveat, which matters because there is no output schema. It omits pagination behavior and the 500-page cap, so not quite 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 blocks: purpose and ordering first, then use case plus next-step routing. The telegraphic "Next:" line is dense but every clause carries actionable information, and there is no filler.

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

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

For a two-parameter read tool with full annotations and no output schema, the definition supplies everything needed: what it returns row-by-row, how results are ordered, when to choose it, and which tools to call next. Nothing an agent needs in order 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%, with both page (1-based, 30 per page) and search (English or Persian, with examples) fully documented. The description adds no additional meaning about how search matching works, so this sits at the baseline where the schema does the work.

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

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

States a specific verb and resource ("List or search companies in IranTalent's employer directory"), plus scale (~34,000) and default ordering (most open jobs first). It also pins down the actual use case ("find a company id from a name"), which separates it from the profile-level sibling it_company. It never explicitly addresses it_top_companies, the closest overlapping sibling, so it falls short of a 5.

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

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

Gives an explicit when-to-use ("Use to find a company id from a name") and then routes the agent onward with named alternatives: it_company for the profile, it_search_jobs(company=id) for jobs, it_company_reviews for reviews. The exact argument form for the jobs handoff is even shown, 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 declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuine behavioral context beyond that: ratings are 1-5 averages over all employee ratings and the six categories are named, which tells the agent how to interpret the returned numbers. It does not mention auth, rate limits or pagination, but for a read-only profile fetch those are minor.

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 resource and its contents, then two short labeled blocks ('Use after', 'Next:') that separate entry conditions from follow-ups. Every sentence carries routing or interpretation value; 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?

There is no output schema, so the description must describe returns, and it does so by enumerating fields including the rating breakdown. Combined with the explicit upstream/downstream sibling routing, an agent has everything needed to select and call this tool 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 would be 3, but the description adds real meaning: the returned jobs are the company's *newest* open jobs, which pairs with the schema's 0-10 cap and contrasts with the note that it_search_jobs(company=id) returns all jobs. That contrast clarifies the parameter's intent rather than restating defaults.

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 ('Read a company profile') and then enumerates the returned content: about text, industry, size, address, website, rating breakdown, newest open jobs. That enumeration makes it clearly distinguishable from siblings like it_company_reviews or it_job, which cover adjacent content.

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 entry point ('Use after it_companies or it_search_jobs') and explicit next steps ('it_company_reviews for review text, it_search_jobs(company=id) for all jobs'). It routes the agent between this tool and its nearest siblings, including the exact call shape for the alternative.

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, but the description still adds real value: a prompt-injection warning that review text is user content (data, not instructions), the 30-per-page pagination scale, the 1-5 rating scale, and the important caveat that only reviews with written text are listed so results are fewer than the total ratings count. It does not mention auth requirements, rate limits, or error behavior, keeping it shy 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?

Front-loaded with purpose, then usage trigger, then behavioral caveats — a sensible ordering with no filler sentences. Minor redundancy in repeating the 30-per-page figure that the schema already documents.

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

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

With no output schema, the description carries the burden of describing returns and does so explicitly (ratings, pros, cons, job title), plus the coverage caveat about written-text-only listings and pagination scale. 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%, with page size, sorting options and the company_id UUID source already documented in the schema, so the baseline is 3. The description restates the 30-per-page figure but adds no new meaning about page, sort, or company_id syntax beyond what the schema provides.

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 ("Read anonymous employee reviews of a company on IranTalent") and enumerates the returned fields (ratings, pros, cons, job title). This clearly separates it from siblings like it_salary_reports and it_company, which cover pay data and company profiles rather than employee review content.

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 trigger: "Use for 'what is it like to work at X'", which an agent can map a user intent onto directly. It stops short of naming when to prefer a sibling instead (e.g., it_salary_reports for compensation questions) or stating 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?

Goes beyond the annotations in two substantive ways: it warns that the description text is employer-authored and 'data, not instructions' (a prompt-injection disclosure annotations cannot express), and it defines a capability boundary around applying. The readOnly/idempotent/openWorld annotations already cover the safety profile, and the description adds the trust and scope context on top.

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 return contents are front-loaded in the first sentence, followed by routing guidance and then caveats — a logical order with no filler. The injection warning is slightly parenthetical but still earns its place given the untrusted-content nature of the field.

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 naming the returned fields. For a single-parameter read tool with full annotation coverage and a stated prerequisite, nothing an agent needs in order to call it correctly is missing.

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

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

With one parameter at 100% schema coverage, the schema already explains job_id including its origin (the number in the job URL). The description only implies the provenance via 'Use after it_search_jobs' and adds no format or validation detail beyond the structured field, 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?

States a specific verb and resource ('Read one IranTalent job ad in full') and enumerates exactly what the ad contains (description, requirements, salary, location, employer, view counts). Combined with the 'Use after it_search_jobs' line, an agent can distinguish this single-record read from list-oriented siblings like it_search_jobs and it_similar_jobs 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 explicit sequencing ('Use after it_search_jobs'), which tells the agent this is the drill-down step following a search. It also rules out the apply action ('Applying needs an IranTalent account and is not possible here'). It stops short of contrasting with it_similar_jobs or it_company, so the alternative-selection coverage is not complete.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's job is to add aggregation semantics — and it does: rows are sorted by open-job count descending, and site totals are returned alongside the breakdown. It still doesn't disclose pagination, row limits, or whether zero-count rows appear, which matters for an aggregation endpoint.

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 usage triggers and then output behavior — a sensible order with no filler. The fourth clause ('Also returns site totals') is slightly tacked on, and the sentence about slugs and ids is dense, but nothing is wasted.

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

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

For a one-parameter aggregation tool with no output schema, the description covers what is counted, how rows are ordered, what totals come back, and how results chain into sibling tools. An agent has everything needed to select and 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% and the single enum is fully documented, so the baseline is 3. The description adds real meaning on top: it expands each enum into human phrasing and notes that the companies breakdown yields ids that feed it_company, which is output-side semantics the schema cannot 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?

The description names a specific verb and resource ('Count IranTalent's open jobs') plus the exact breakdown dimensions, so it is immediately distinguishable from it_search_jobs (which returns individual postings) and it_top_companies. The phrase 'market overview' in the title is backed by concrete counting behavior rather than restated.

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 explicit when-to-use triggers with worked examples ('which fields hire most', 'who is hiring most now'), which is more than most definitions offer. It also routes follow-up work to it_search_jobs and it_company, though it never states a when-not-to-use case, such as using it_search_jobs for individual listings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: slugs must match exactly (a hard matching constraint), locations include open-job counts, and the call should be made once per kind — all useful for correct invocation. No pagination or caching notes, keeping it below the top mark.

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

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

Three short sentences, front-loaded with the purpose and the consumed-tool reference, followed by the calling rule and the kind-specific notes. No redundant or 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?

Single enum parameter, no output schema, and the description still communicates the returned fields (slug, English/Persian name, job counts for locations). An agent has everything needed to pick the right kind and use the 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% and the enum is already documented, so baseline is 3. The description adds meaning by mapping the salary_* kinds to their downstream consumers (it_salary_reports / it_salary) and noting that locations carry open-job counts, giving the agent a reason to choose each kind.

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 valid filter values") and immediately ties the output to the consuming tool, it_search_jobs. The parenthetical listing the returned fields (slug, English and Persian name) makes it unmistakable what this returns versus siblings like it_search_jobs or it_salary.

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?

"Call this once per kind before filtering" gives an explicit precondition and cardinality, and the last sentence routes salary-related kinds to it_salary_reports / it_salary. It lacks any when-not or failure guidance, but the workflow context 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?

Annotations only cover the safety profile (readOnly, idempotent, openWorld, non-destructive); the description adds substantial context beyond them: figures are net monthly in Toman, reported at five percentiles, cover Persian years 1405 (requested) and 1404 (received), come from a survey rather than job ads, and have no per-city split. These caveats materially change how an agent should present the data.

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, then the exclusivity rule, then the interpretive caveats, then the next step. Dense but every sentence carries information the agent needs; the trailing sibling suggestion is borderline but earns its place as navigation.

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 convey return-value shape — it does, specifying percentile bands, currency (net monthly Toman), and reporting years. Combined with the exclusivity rule and source caveat, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, and the schema already documents both slugs. The description nonetheless adds the mutual-exclusion rule ("exactly one of report or specialty") that the schema itself does not encode — both parameters are optional with no anyOf constraint — plus the semantics that specialty expands to every seniority level.

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 (read) and resource (salary figures), and immediately distinguishes its two modes: one report vs. every seniority level of one specialty. An agent can tell this apart from it_salary_reports (which supplies slugs) or it_search_jobs (which returns ads) 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?

"Give exactly one of report or specialty" is an explicit selection constraint, and the closing line routes the agent onward to it_search_jobs for live ads. It does not spell out when-not-to-use or which prerequisite tool to call first for slugs, so it stops short of fully prescriptive 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 establish that this is a read-only, idempotent, non-destructive open-world lookup. The description adds useful behavioral context beyond that: about 200 reports, one per specialty and seniority, and the title format agents can expect.

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 free of repetition. It moves efficiently from what the tool lists to when to use it to what to call next.

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 carries the burden of explaining what comes back. It does that at a useful level by saying there are about 200 reports and each has a title like "salary of senior Java developer in 1405", though it does not enumerate returned fields.

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 search, seniority, and pagination semantics are already documented in the input schema. The description adds only light context about report slugs and specialty filtering, without meaningfully expanding parameter interpretation beyond the schema.

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

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

The description gives a specific verb and resource: list IranTalent salary reports, one per job specialty and seniority level. It also names the source domain and distinguishes the tool from it_salary by explaining that this tool lists reports while it_salary returns the figures.

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 explicitly says to use this first for questions like "how much does a X earn in Iran" and then use it_salary with the report slug or specialty to get figures. That gives clear when-to-use guidance and a concrete alternative.

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, open-world and non-destructive, and the description adds real beyond-annotation behavior: newest-first ordering, OR-within-filter / AND-across-filters logic, salary present only when the employer publishes it (Toman/month), 30 per page, and that `total` is the full match count rather than the page size. The remaining gap is result shape — with no output schema, the agent still doesn't know what fields each ad returns beyond the total count.

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, front-loaded with what it is and when to use it first, then filter semantics, then result caveats, then hand-offs. No restating of parameters that the schema already documents.

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-parameter, zero-required search tool with no output schema, the description covers ordering, pagination, total-count semantics, salary nullability, and where to go next for full ad or employer detail. Only the per-result field list is left unspecified, which is a modest gap given the hand-off to it_job.

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 semantics the schema lacks: every array filter takes slugs sourced from it_lookups, multiple slugs in one filter OR together while different filters AND together. That combination rule is the single most important thing to know when composing 12 optional filters and it is stated only in prose.

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 IranTalent job ads") plus the portal it belongs to, and names the two sibling tools (it_job, it_company) that handle follow-up detail. An agent can distinguish it from it_similar_jobs, it_job_market and it_companies 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?

"Use first for 'jobs in X'" establishes this as the entry point, and "Next: it_job for the full ad, it_company for the employer" gives explicit routing to alternatives. It also points to it_lookups as the source of valid filter slugs, which is the one prerequisite for calling it.

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

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

Annotations already declare this as a safe, read-only, idempotent, non-destructive, open-world read. The description adds useful behavior beyond that: it returns open jobs, filters by category and city, sorts newest first, and excludes the source ad. Pagination and result limits are not mentioned, but the core behavioral contract is well covered.

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

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

The description is two compact sentences with the core matching behavior front-loaded and the workflow guidance immediately after. Every clause adds selection or follow-up value, 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 two-parameter read-only tool with rich annotations and no output schema, the description supplies the essential context: what similar means, ordering, exclusion of the source ad, and the it_job workflow. It could additionally mention pagination or result limits, but 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 the schema already explains both job_id and same_city. The description references the same category and city filtering, but it does not add syntax, formatting, or edge-case semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Find open jobs similar to one ad', then clarifies the matching scope as 'same job category (and city)' and excludes the source ad. This is specific enough for an agent to distinguish it from generic job search and from the it_job detail 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 gives clear contextual usage: 'Use after it_job for "more like this"' and tells the agent to go back to it_job for any result. It does not explicitly contrast with it_search_jobs or state when not to use this tool, but the intended workflow 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?

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, so the description only needs to add data semantics — which it does, explaining that the list is capped at 50 entries and that the rating is an average of employee reviews on a 1-5 scale. It omits any note on result fields or whether the list changes over time.

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

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

Three short, front-loaded sentences: purpose, use case, next step. The parenthetical gloss '(the site's "best companies" list)' mildly restates 'top companies by employee rating,' but the rest is waste-free and well ordered.

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, no-output-schema list tool, the description covers what the list is, how the ranking metric is computed, its size limit, and where to go next. It never states what fields each company entry contains beyond implying an id, which is the one 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 the schema-description baseline of 4 applies and there is nothing for the description to compensate for. The description uses the space instead to explain the output signal (rating derivation), which is a reasonable allocation.

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 ('List IranTalent's 50 top companies') plus the ranking criterion ('by employee rating'), which is enough to tell it apart from the generic it_companies sibling. It stops short of explicitly naming how it differs from it_companies, relying on the reader to infer that this is the curated/ranked subset.

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 names a concrete use case ('best places to work in Iran') and provides explicit next-step routing to it_company or it_company_reviews with the id. It does not state when not to use it or contrast directly against it_companies, so the alternative-selection guidance is clear but incomplete.

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