JobCrawls

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

Annotations already establish the read-only idempotent safety profile, and the description adds substantial context beyond them: locale detection rules, the returned breakdown fields, the current-tax-year basis, and an explicit 'estimate, not tax advice' caveat.

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?

A single dense paragraph, but front-loaded with purpose and examples, and nearly every sentence carries distinct information (inputs, exclusions, locale, returns, caveat). Slightly heavy, yet nothing is 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 15-parameter zero-required calculator with an output schema, the description covers inputs, edge cases (locale/municipality interplay), output shape, and limitations. Since an output schema exists, the return-value prose is bonus rather than a 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: the gross-vs-net mutual-exclusion intent, the period default, and the interaction where municipality's language form drives locale detection. It adds real value on top of a fully documented 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 ('Gross-to-net salary calculator for Finland') plus the domain context (JobCrawls tax iceberg calculator). It is trivially distinguishable from the job-search siblings, which share no overlap.

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 example questions in three languages, explains the gross-or-net input modes, enumerates the optional dimensions, and states explicit exclusions ('does not accept church membership or union fees'). An agent knows exactly when and how to call 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds real behavioral context the annotations cannot: the isTyomarkkinatori:true flag, the mandatory `dataSource` attribution per Job Market Finland terms, and the locale fallback when a listing is missing in the requested language. It stops short of noting what happens for an unknown id or an unreachable source, which keeps it at 4.

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, front-loaded with purpose, then usage, then the compliance caveat. The mid-sentence enumeration of returned fields is slightly padded, but the ordering is sensible and no sentence is redundant 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 an output schema present, the description need not explain return values, yet it flags the one return detail with legal consequences (the required dataSource attribution) and the locale fallback behavior. Combined with the annotations, an agent has everything needed to 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%, so the baseline is 3, and the schema already documents jobId's format and locale's enum/default. The description adds cross-tool meaning by telling the agent that jobId comes from the `id` field of a search_jobs result, which is genuine value beyond the schema text.

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 ('Fetch the complete details for a single JobCrawls listing by its id') and enumerates the returned payload. It also positions itself relative to the sibling search_jobs, so an agent can distinguish this retrieval call from the search call 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?

Explicitly names the trigger condition ('Useful after search_jobs when a user wants to know more about a specific opening') and the alternative it follows from, plus the data dependency ('takes the `id` field from a search_jobs result'). Nothing about when to reach for this tool is 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 readOnly/idempotent/non-destructive with openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: results are counts per value, they are localized, values reflect 'currently present' active listings, and the default language is derived from the query unless locale is passed.

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, front-loaded with the resource description, then the downstream contract, then the optional scoping/locale rules. Every sentence carries information, though the locale sentence overlaps somewhat with the schema's own locale description.

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 facet-listing tool with a full output schema and complete parameter descriptions, nothing an agent needs is missing: what is returned, how counts work, how values relate to search_jobs, and how locale/query interact are all covered.

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 baseline is 3. The description goes beyond by linking the parameters to downstream use: query scopes values to a subset (e.g. only facets in 'nurse' jobs) and the same locale must be reused in search_jobs, reinforcing the schema's localization semantics with cross-tool intent.

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+resource (returns the facet attributes jobs can be filtered by) and enumerates concrete examples (field, location, job type, seniority, skills, languages). It clearly positions itself as the discovery companion to search_jobs rather than a search tool, so an agent can distinguish it from its siblings 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?

States precisely when the output is useful: the returned values are 'the exact strings search_jobs accepts in its filters parameter for the same locale,' which tells the agent to call this before search_jobs and how to feed results back. It explains the query-scoping and locale-override conditions. It lacks an explicit when-not-to-use clause, but the 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds non-obvious behavioral obligations: the mandatory dataSource attribution for Työmarkkinatori results, the isTyomarkkinatori flag, locale-driven result language, and paginated scoping. This is exactly the value-add expected when structured fields already carry the basics.

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-loads the core purpose and scope, then layers filters, locale, return shape, and attribution in a logical order. Dense but each sentence carries information; the locale explanation is somewhat redundant with the schema and could be tightened.

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 10-parameter, nested-filter, output-schema-backed search tool, everything an agent needs is present: scope, examples, filter mechanics, locale semantics, sibling routing, and legal attribution requirements. Return values are covered by the 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 baseline is 3, but the description goes beyond it by explaining cross-parameter/cross-tool coordination: facet values must match the selected locale index and be discovered via list_job_filters with the same locale, and locale must track the user's message language. It adds little on pagination/sort, which the schema already covers.

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 active job listings on JobCrawls, an aggregator of jobs in Finland') and pins the geographic scope precisely, explicitly excluding Stockholm/Berlin. An agent can distinguish it from list_job_filters and get_job_details 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 examples in three languages, states the scope boundary (Finland-located plus remote-open-to-Finland, nothing else), and routes to siblings: list_job_filters for filter values and get_job_details for full descriptions. Both when-to-use and when-not-to-use are covered.

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