get_salary_statistics

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

No annotations are present, so the description must carry all behavioral disclosures. It transparently notes the fallback to vacancy sampling is biased, which is crucial. It also explains the 401/403/404 triggers. However, it does not mention that the operation is read-only or any potential rate limits, and it doesn't describe the output format, so some transparency gaps remain.

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 about three sentences, front-loaded with the main purpose. It efficiently packs the two-mode logic without excessive verbosity. It's concise but not overly terse, and the structure flows logically from purpose to mode details.

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 the tool's complexity (9 parameters, no output schema, no annotations), the description explains the two modes and parameter roles but does not describe the return value or any formatting. It also lacks guidance on typical use cases or examples. The biased fallback is mentioned, but error handling beyond the fallback is omitted. This leaves some gaps for an agent deciding whether and how to call the tool.

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

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

The schema already documents all parameters, so baseline is 3. The description adds valuable semantic context: it clarifies that speciality, employee_level, industry, and extend_sources are only for the paid bank, and that text maps to position_name. It also explains area_id's dual role. This goes beyond the schema's individual 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 clearly states the tool provides salary distribution for a role/region, distinguishing it from sibling tools like search_vacancies or get_vacancy_stats. It also explains the dual mode (paid bank vs fallback), which adds specificity. However, it doesn't explicitly name alternative tools, so it's slightly less clear on differentiation, but the purpose is unmistakable.

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 explains when the paid bank is attempted (with token and area_id) and when fallback occurs (on errors or missing token/area). It implies this tool is for salary statistics, but doesn't explicitly contrast with alternatives like get_negotiations_statistics or search_vacancies. It gives context on parameter usage but no exclusions.

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