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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds real value beyond them by disclosing what the response contains and, importantly, what it does NOT contain (no reviews or ratings), which prevents misuse. It stops short of stating auth, rate-limit, or error behavior for a bad slug, keeping it off a 5.

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

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

Three short sentences, front-loaded with the payload description, then the usage cue, then the sibling redirect. No filler and no repetition of the title.

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

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

For a one-parameter read-only lookup with no output schema, the definition is complete: it lists the return fields so the agent knows what it gets, states when to call it, and routes two adjacent needs to the correct siblings. Nothing required 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 'slug' parameter already documents its pattern, source URL, and an example, so the schema does the heavy lifting. The description only indirectly adds context by saying the call follows a job or company search, implying where the slug originates. That is a marginal contribution over structured data, 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 opens with a specific verb and resource ('Read a company's Jobinja profile') and immediately enumerates the returned fields (name, founding year, industry, size, website, open job count, intro, culture, benefits). It also differentiates itself from siblings by name, pointing to jj_company_jobs for ads and jj_top_companies for the top-50 score.

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?

Explicit triggering context is given ('Use after a job or company search') along with a named alternative for a related need ('Call jj_company_jobs for the open ads'). It additionally pre-empts a likely wrong expectation by stating Jobinja has no employee reviews or ratings, so the agent knows not to seek such data here.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add context beyond that. It does: expired ads reveal hiring history, and expired pages hold 100 ads each, which tells the agent how paging behaves. Missing rate-limit or total-count behavior 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 primary mode before the alternate mode and the chaining note. Nearly every sentence earns its place, with only mild redundancy between the parenthetical and the closing page-size remark.

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 must convey the return shape, and it only partially does ('each row has an id') without naming other row fields. Paging behavior is covered for expired mode but not for the default open-jobs listing, and failure behavior for a bad slug is unaddressed.

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

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

Schema coverage is 100%, so the schema already documents slug, limit and expired_page, making 3 the baseline. The description reinforces the intent of expired_page (past ads / hiring history) and the 100-per-page relation to limit, but adds no format or syntax 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 a company's open job ads on Jobinja', with a clearly scoped alternate mode via expired_page. The company-scoped framing implicitly separates it from jj_search_jobs and jj_job, though no sibling is named explicitly.

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

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

'Use to see what a company is hiring for' gives a general context for selection and the note that each row has an id for jj_job supplies a useful follow-up chaining hint. However, it never says when to prefer jj_search_jobs or jj_company instead, nor any prerequisite or exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the agent knows this is a safe, repeatable read against an open value set. The description adds the useful framing that these are the accepted search values, but says nothing about response size, whether values are stable/cacheable, or how they are grouped.

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 padding. The value enumeration comes first and the practical trigger second, which is the right front-loading for a reference tool.

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-only lookup with no output schema, the description carries most of what is needed: it tells the agent which value families come back and why to call it. It stops short of describing the response structure (flat lists versus grouped by family), which is the main remaining gap given 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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description does not misrepresent anything about invocation and correctly implies the call needs no arguments.

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 every value the Jobinja search accepts') and enumerates exactly which value families are covered: provinces, job categories, industries, experience levels, salary steps, sort orders. That enumeration is what separates it from the sibling search tools (jj_search_jobs, jj_search_companies), which return entities rather than allowed values.

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 trigger: use it when a province, category or industry name is rejected, or when the exact spelling is needed. This is clear when-to-use guidance for the primary failure mode. It does not name an alternative tool or state when not to use it, which keeps it below 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, so the description is not burdened with the safety profile. It adds real behavioral context that annotations cannot: the salary is a monthly Toman figure representing a minimum or a negotiable amount, and the returned `expired` flag must be checked before recommending the ad. It does not cover what happens on an invalid or stale job id.

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 core purpose and the returned-field list are front-loaded, followed by usage routing and data caveats. Three compact sentences with no filler; only the salary sentence is slightly long, but it carries genuine semantic value.

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 listing the returned fields is necessary and done well, and the `expired` and salary caveats cover the main interpretation pitfalls. Only failure behavior for an invalid or expired job id is left unexplained.

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 `job` parameter is already documented with the 'company-slug/token' format and URL alternative. The description adds no additional parameter 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?

States a specific verb and resource ("Read one Jobinja job ad") and enumerates the fields returned, so an agent can immediately distinguish it from the plural search siblings like jj_search_jobs. The scope is unambiguous: exactly one job record.

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

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

Gives explicit sequencing ("Use after jj_search_jobs or jj_company_jobs") and routes the agent elsewhere for a related need ("Call jj_company with company_slug for the employer"). It lacks an explicit when-not condition (e.g., what to do for multiple jobs), but the alternatives are 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds that results are live site statistics ("right now"), which is meaningful freshness context beyond the annotations. It does not cover rate limits or how large the returned breakdowns are (e.g. whether 'top skill' is capped).

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

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

Two short sentences, front-loaded with the core capability, then usage. No filler, and the province-specific behavior is attached to the guidance where it is actionable.

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

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

For a single optional-parameter, no-output-schema tool, this covers what is counted, the breakdown axes, and the special province mode. Minor gap: it doesn't indicate how the counts are grouped/limited in the response (top-N skills, ordering), though that is partly implied by 'top skill'.

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 explains the province parameter lists cities with ad counts. The description adds real meaning on top: the city names returned are intended to feed the city filter of jj_search_jobs, which the schema does not say.

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 (count) and resource (open Jobinja ads) plus the exact breakdown dimensions: job category, province, company industry and top skill. This is clearly an aggregate/statistics tool, so an agent can distinguish it from jj_search_jobs and jj_filters 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 concrete trigger questions ("how many programming jobs are open", "which province hires most") and names the alternative path: use the province parameter when you need city names for jj_search_jobs' city filter. This is explicit when-to-use plus sibling routing.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the request cost model ('one request per sampled ad, at most 30'), the data-quality caveat ('most ads say negotiable, so check n_with_salary'), and a reporting obligation ('A sample, not a survey: say so when reporting'). These are exactly the behavioral facts an agent needs before committing to a multi-request call.

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

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

Front-loaded with the core action and unit, then caveats, then cost. Every sentence carries distinct information: mechanism, trigger, limitation, output usage, and request budget. No filler.

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

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

With no output schema, the description carries the return-value burden and does explain that ads are returned and that `n_with_salary` should be checked. Field names like `n_with_salary` and the exact shape of the summary are not fully specified, leaving a small gap for a tool with 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?

Schema coverage is 100%, so all six parameters are already documented. The description mostly restates the `sample` bound and its per-request cost, which duplicates the schema text ('each is one request'), and the keyword example adds only mild context. 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: 'Estimate monthly salaries (Toman) for a kind of job by reading the ad pages of the top search results.' It also discloses the mechanism (sampling ad pages) and the unit (Toman), which separates it from jj_search_jobs (raw listings) and jj_market (aggregate market 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?

Gives an explicit trigger phrase ('what does a python developer earn') and explains why the alternative fails: 'Lists hide salaries,' implying jj_search_jobs alone won't answer salary questions. No explicit named alternative or when-not-to-use case is given, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. Beyond them the description adds genuinely new context: a fixed page size of 8 and the rule that industry overrides keyword. Return shape is only partially disclosed via the mention of slugs.

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 no filler; the primary purpose and page size come first, followed by the downstream-use rationale and parameter rule. 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?

With no output schema, the description compensates by stating the tool returns slugs usable by jj_company and jj_company_jobs, and it discloses the page size. It leaves a small gap: the all-optional parameter set means the behavior with no arguments (browse all companies?) is unspecified.

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 still adds meaning the schema lacks, namely the mutual-exclusion precedence ('industry wins') and the explicit framing of the two optional inputs as alternative modes.

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 companies on Jobinja') and enumerates the two distinct modes: keyword search by name, or browsing a single industry. The resource (companies) inherently separates it from jj_search_jobs, and the 8-per-page detail makes the scope concrete.

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 when-to-use guidance ('Use to get the slug for jj_company / jj_company_jobs') and resolves precedence between the optional params ('industry wins'). It stops short of stating what happens when neither keyword nor industry is supplied, or when to prefer jj_top_companies over browsing.

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 adds genuinely new behavioral facts: 20 ads per page, which fields come back (id, company, city, contract type, age), that salaries are hidden in list results, and that filters combine with AND. The salary-omission disclosure in particular prevents a wasted call and justifies the hand-off to jj_job.

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 first, then usage/example mapping, then return-shape caveat and the alternative tool. No redundant restatement of the schema and no filler.

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

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

With 12 optional parameters and no output schema, the description carries the return-shape burden itself by listing the returned fields and the page size, plus the salary gap and the AND-combination rule. Pagination bounds live in the schema, so nothing material an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description itself mostly restates the filter dimensions already documented in the schema and adds no syntax or format information beyond it. The one semantics note ('filters combine with AND') is behavioral rather than parameter-level, so the baseline holds.

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 ('Search Jobinja job ads') and enumerates the filterable dimensions (keyword, province, city, category, remote, contract type, experience, benefits, minimum salary). It also distinguishes itself from siblings by pointing to jj_job for detail lookups and to jj_filters/jj_market for lookup values, so the agent can place it in the tool family without opening another schema.

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

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

Gives concrete trigger examples ('find python jobs in Isfahan', 'remote jobs paying 50 million') that map directly onto parameters, and explicitly routes to jj_job with an id when salary/skills/full description are needed. It stops short of stating when NOT to use this tool (e.g., vs jj_company_jobs for company-scoped listings or jj_search_companies), so it is clear-but-not-exhaustive rather than a full 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds a non-obvious and material caveat: counts include expired ads and therefore rank skills rather than reflect current openings — a semantic trap an agent would otherwise fall into. It stops short of describing matching behavior (substring vs exact) or how many skills come back.

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, both earning their place: the first defines the tool and its output, the second handles usage and the critical caveat. The important limitation (expired ads included) is placed before the sibling handoff, so it is read before the agent acts.

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-param read-only tool with no output schema, the description covers what the tool does, when to use it, the alternative, and how to interpret the counts. The only mild gap is the unstated result shape and whether matching is substring-based, but annotations and the simple schema carry most of the remaining weight.

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 param is documented with examples, so the baseline is 3. The description goes slightly beyond by framing the query as a word to match and by noting the result helps "pick the exact skill spelling," which implies partial matching returning multiple candidates rather than an exact 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 ("Find skills on Jobinja matching a word") plus the returned payload ("how many ads ever listed each"). The parenthetical "(a demand signal)" frames the value, and the description implicitly separates it from jj_search_jobs, which lists ads rather than skills.

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 ("compare skills ('react vs vue')", "pick the exact skill spelling") and an explicit when-not with the named alternative: "use jj_search_jobs for those" when you want today's openings. Routing between this tool and its sibling 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the data is yearly (recency caveat), it is a ranked top-50 list, and the three sub-scores are named so the agent knows what the numbers mean. It omits ordering/ranking guarantees and whether limit returns the top N by rank, 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?

Three short sentences, front-loaded with what the tool returns, followed by the differentiating claim and the sibling routing hint. No redundant restatement of the name or title, and every sentence adds 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?

The tool is simple (one optional bounded parameter, no output schema), and the description compensates for the missing output schema by describing what each record contains: overall score out of 10 plus three named sub-scores. Combined with annotations and a fully documented parameter, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with 'limit' documented as 'How many of the 50' and bounded 1-50, so the schema carries the semantics. The description adds nothing further about the parameter, such as whether limited results are the highest-ranked companies. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific resource and scope ('Jobinja's yearly list of the 50 best companies to work for') plus what each entry contains (score out of 10 and three sub-scores). It also explicitly distinguishes itself from the other company tools by claiming 'This is the only company rating data on Jobinja', so an agent can separate it from jj_search_companies.

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 follow-up route ('Use the slug with jj_company'), which tells the agent this is a discovery step feeding another tool. It also implicitly frames when to use it by saying it is the only source of rating data. It stops short of explicitly contrasting with jj_search_companies or stating when not to use it, so it is clear context rather than 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.