Jawne Stawki

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds only the geographic/contract/experience scoping, and says nothing about response shape, whether a/b must be resolved via search_occupations, or error behavior when a name is ambiguous.

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 comparison action and the scoping detail in parentheses. The Polish/English duplication costs some space but is a deliberate bilingual accessibility choice rather than padding.

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

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

For a read-only, closed-world comparison tool with full schema coverage and annotations, the description covers the essentials. It is thin on the one thing the schema cannot express for a 'compare' tool: what the side-by-side result actually contains, which matters since no output schema exists.

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 enum parameters fully documented in the schema, so the baseline is 3. The description's parenthetical about city/contract/experience merely restates the optional parameters without adding format or default semantics beyond what the schema already gives.

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 (compare) and resource (salaries of two occupations), with a clear scope of 'two occupations in Poland' that separates it from the single-salary sibling get_salary. It never names get_salary or search_occupations, however, so the differentiation is inferable rather than explicit.

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

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

It states the scoping options (whole country or a city, optionally contract and experience), which implies when this tool applies, but it gives no explicit when-to-use versus get_salary or search_occupations and no prerequisite telling the agent to resolve occupation IDs first.

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, and destructiveHint=false, so safety is covered. The description adds useful behavioral context about what data is returned (medians in two contract types, national comparison, top-demand occupations), but says nothing about data freshness, coverage limits, or error behavior when an unknown city is supplied.

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: the first is a dense, front-loaded enumeration of the metrics returned, the second is a concise English summary. No filler, no repetition of the tool name, and the most important information comes first.

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

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

For a read-only, single-parameter, no-output-schema tool, the description is largely complete: it tells the agent what the tool returns and what input shape to expect. It only falls short on how this tool relates to its salary-focused siblings, which is the one missing piece an agent would need for disambiguation.

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

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

Schema description coverage is 100% and the single parameter has a clear description with example values ('Kraków', 'gdansk'), so the baseline is 3. The tool-level description reinforces that the parameter scope is a Polish city, which is modest added value. With one parameter and full schema coverage, a 4 is appropriate.

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

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

The description names a specific resource (city salary data in Poland) and enumerates the concrete metrics returned: offer count, medians (UoP/B2B), pay relative to the national average, and in-demand occupations. This is much more than a restatement of the name. However, it does not explicitly distinguish itself from siblings like get_salary or get_rankings, which likely return overlapping salary 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?

Usage is implied: fetch city-level salary aggregates. But there is no explicit when-to-use guidance, no mention of when to prefer get_salary or get_rankings instead, and no stated condition that selects this tool over its siblings. The agent must infer the boundary from the description's content alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds useful scope context (median, umowa o pracę and B2B) but says nothing about result ordering, whether both rankings are always returned, or pagination behavior.

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 compact sentences, front-loaded with the core content. The bilingual duplication is mildly redundant but serves a mixed-language audience without bloating the 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?

For a simple read-only, single-optional-param tool with no output schema, the description conveys the content scope well enough to call it correctly. Only minor gaps remain around return shape and how the two rankings are combined.

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?

Single parameter with 100% schema description coverage, so the schema already documents 'limit' with its default and range. The description adds nothing about the parameter, which is the baseline 3 when 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 the resource precisely: best-paid occupations (both employment contract and B2B, median) and most in-demand occupations in Poland. This distinguishes it from get_salary and compare_occupations, though it doesn't name those siblings explicitly. Clear verb-less but unambiguous purpose.

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

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

The description implies usage (get rankings of pay/demand) but gives no explicit when-to-use guidance or routing against siblings like compare_occupations or get_salary. The distinction is inferable from content, not stated.

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

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

Annotations already declare this as a safe, idempotent, closed-world read operation, covering the safety/mutation concerns. The description adds context about output content (percentiles, GUS data), which is useful, but doesn't mention retrieval constraints, caching, or data freshness/currency.

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 mixes Polish and English, then partially repeats the same content in English, and lists output fields that overlap with the schema-defined parameters. It's moderately front-loaded but not perfectly tight; the bilingual restatement adds authoring overhead without new 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 single read tool with full schema coverage and no output schema, the description gives enough for expected return content but doesn't detail response shape, pagination, or edge cases. It's adequate but not rich, and its remaining gap is the exact output format since there's 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 description coverage is 100% – every parameter (city, contract, experience, occupation) is fully documented in the schema with enums, examples, and semantics. The description largely restates these (contract types, experience seniority) without adding format or syntax detail the schema lacks, so baseline 3 is appropriate.

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

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

The description clearly states it returns salary statistics (median, quartiles, typical ranges) for an occupation in Poland or a city, and mentions supporting breakdowns by contract type and experience. It's a specific verb+resource, but unlike the sibling-routing example it doesn't contrast itself with compare_occupations or get_rankings, which could also involve salary 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?

Usage is implied (need an occupation identifier, optionally a city/contract/experience) but there's no explicit when-to-use-vs-alternatives guidance. The description doesn't distinguish this from compare_occupations, which likely does salary comparison, leaving the agent to infer the boundary.

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 and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context by stating what comes back (offer count and median salary), which annotations cannot express. It omits any note on default/max result limits despite the schema capping limit at 20.

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 Polish sentence is front-loaded and information-dense, covering purpose, input form, and output. The trailing English sentence is largely a restatement for non-Polish readers, which is mildly redundant but defensible for a bilingual 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?

With no output schema, the description correctly compensates by naming the returned fields (offer count, median salary) and the identifier. Combined with full schema coverage for both parameters, an agent has enough to invoke it, though result-limit behavior remains unstated.

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 would be 3. The description goes beyond it by giving four concrete query examples ('magazynier', 'pielęgniarka', 'programista java', 'devops'), clarifying that partial/compound names and English-tech terms in Polish text are acceptable. It adds no guidance on the limit parameter.

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

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

States a specific verb and resource (find an occupation by Polish name) and even names the payload (occupation id, offer count, median salary), which is more than the title conveys. It does not distinguish itself from siblings like get_salary or compare_occupations, so an agent must infer the boundary on its own.

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

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

Usage is implied: search by Polish name/fragment to obtain an occupation identifier that presumably feeds other tools. There is no explicit when-to-use or when-not-to-use statement, and no mention of the alternatives (get_salary, compare_occupations) already exposed in the sibling list.

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