GWIX

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds genuinely new context — that the call is free (no credit consumption) and what data is returned (lots with expiry) — but says nothing about staleness, units, or freshness of the balance.

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 short sentence, front-loaded with the resource and followed by the returned data and the cost note. Nothing is padded or repeated from 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?

With no parameters, no output schema and rich annotations, the description carries only the burden of explaining what comes back, which it does. Minor gaps remain around currency/units and whether the balance is real-time, but an agent can call this correctly as written.

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 nothing for the description to document; baseline 4 applies. No parameter detail is missing because none exists.

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 the specific resource and its contents: the organization's credit balance, credit lots with their expiry, and usage. That is concrete enough to distinguish it from every sibling (which cover pay, postings, fx rates, dimensions, etc.). It lacks an explicit verb, but the retrieval intent is unambiguous.

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 only implied — an agent infers it should call this when it needs credit/balance information, and 'Free' signals there is no cost to calling it. There is no explicit when-to-use statement and no routing against siblings like data_status or gwix_summary, though none of them obviously overlap.

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, open-world behavior, but the description adds important operational context: a 30-90 second run time, credit consumption, and free Ask GWIX answers being used first. It also says every figure is cited and lists the source types combined. This is exactly the kind of beyond-annotation behavior an agent needs.

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 front-loaded with the use case and remains focused on selection guidance and behavior. It is somewhat verbose in the middle, with a long parenthetical and source list, but those details are relevant rather than decorative. It is efficiently organized, if not maximally tight.

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 explain the return shape, and it does: percentiles, trends, comparisons, chart data, interpretation, and citations. It also covers latency and credit behavior. Given the tool's complexity, this is complete enough for an agent to set expectations and invoke 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%, so the single parameter is already documented by the schema. The description reinforces that the tool takes a user's question but adds no extra syntax, formatting, or constraints beyond the schema's own description. A baseline 3 is appropriate when the schema fully carries the parameter semantics.

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: it answers a question with a full, multi-source GWIX report. It distinguishes itself clearly from siblings by saying the other tools are for a specific figure, lookup, or data to build on. The scope is concrete enough that an agent can choose this tool without opening any schemas.

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 when to use this tool: any pay, hiring, labor market, company, occupation, or economy question, after gwix_summary when applicable. It also names the alternative pattern: use the other tools only for a specific figure, a lookup, or data to build on. That is direct routing guidance with a clear 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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new context: the mapping always lands on SOC 2018 occupations plus the GWIX roles their ads fall in, which is important behavioral information with no output schema present.

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, front-loaded with 'Use for:' so intent matching happens immediately. There is mild redundancy in listing the taxonomy set twice (once in the intent sentence, once in the mapping sentence).

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 4-parameter read tool with no output schema, the description tells the agent what comes back (SOC 2018 occupations and associated GWIX roles), which is the main missing piece. It leaves the relationship between from_system/to_system direction implicit, but overall it is sufficient to call 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 75% and the enum plus 'to_system' default 'both' and 'roles_limit' default 10 are already documented in the schema. The description restates the supported from_systems and code examples rather than adding format or edge-case semantics, so it sits at the baseline for high coverage.

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 (map) and resource (occupation codes across SOC/O*NET/ISCO/ESCO/GWIX), and the 'Use for:' phrasing frames the user question it answers. It does not explicitly differentiate itself from ambiguous siblings such as 'lookup' or 'describe', 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?

The opening 'Use for: what is this SOC... code in another taxonomy, or which occupation codes a job maps to' gives concrete triggering intents, which is stronger than most tools. It stops short of 5 because there is no statement of when NOT to use it or which sibling to prefer for adjacent lookups.

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, non-destructive and closed-world, so the safety profile is covered. The description contributes one genuinely extra behavioral fact — that the call is free — but says nothing about freshness guarantees, caching, or whether the country argument changes cost.

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?

One short sentence plus a cost token, front-loaded with the primary return value. Every clause carries information, though the sentence is a noun fragment with no verb and 'Free.' reads as an afterthought.

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, safe, single-parameter read tool this is close to adequate, and annotations cover the safety profile. However, with no output schema, the description never characterizes the shape of the returned release/week/coverage data, leaving the agent to guess what it will get back.

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% with a single optional 'country' parameter documented as ISO-2. The phrase 'coverage per country' hints that the parameter narrows the coverage report, but the description adds no format or default behavior (e.g., what is returned when country is omitted), so 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?

The description names the three things the tool returns — the live data release, the last complete week used by statistics, and per-country coverage — which is specific enough to distinguish it from siblings like list_periods or gwix_summary. It lacks an explicit verb (retrieve/report), but the resource content is unambiguous.

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?

There is no statement of when to call this versus alternatives such as list_periods or list_dimensions, and no prerequisites. The only guidance is 'Free.', which is a cost note rather than a usage condition.

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 closed-world, so the safety profile is covered. The description adds value by disclosing the shape of the result (name, parents, attributes), which matters because no output schema exists. It says nothing about behavior on an unknown ID or whether a missing parent is returned as null.

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?

One compact sentence with no filler, and the resource being described is front-loaded. It is a fragment rather than a full clause, 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 2-parameter read tool with no output schema, the description covers the essentials of what comes back but leaves the dimension/id pairing and error behavior unspecified. It is adequate but not complete.

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 50%: 'id' is documented only as 'The ID.' and 'dimension' carries an enum but no description. The parenthetical list of attribute kinds loosely glosses the dimension values (roles, job families, SOC occupations, job levels, companies, industries, locations), which helps the agent pick a dimension, though 'sub_job_family' is never accounted for.

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 the resource (a GWIX ID) and what it returns: the name, parents, and attributes behind that ID. That is concrete enough to know it is a resolve/expand operation, but it never distinguishes itself from the sibling tools 'lookup' and 'crosswalk', which plausibly do something similar.

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?

There is no statement of when to call this versus 'lookup', 'crosswalk', or 'list_dimensions'. The agent must infer from the name that this expands a single known ID rather than searching for one.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description usefully adds rate direction (units per USD) and that calls are free, but says nothing about default behavior when no filters are supplied or how results are ordered or paginated.

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 the core semantics front-loaded and zero filler. The fragment 'Free.' and the undefined acronym 'GWIX' make it slightly more telegraphic than ideal, 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?

With five optional parameters and no required ones, an agent needs to know what happens with an unfiltered call (all currencies? all periods?) and what a period 'label' looks like. Neither is addressed, though the absence of an output schema is offset by the description stating the units of the returned rates.

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 80%, so the schema largely documents country, currency and the enum interval; the description only reinforces 'per currency and period'. It adds no clarity on the opaque 'label' format for start_period/end_period, which is the least self-explanatory part of 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 names the specific resource (exchange rates) and adds meaningful semantics: rates are the ones GWIX used, expressed as units per USD, per currency and period. That is enough to distinguish it from generic siblings like lookup or crosswalk, though it never explicitly contrasts with them or states the retrieval verb.

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?

There is no guidance on when to call this tool versus siblings such as crosswalk or lookup, and no mention of prerequisites. The only usage-adjacent signal is 'Free.', which speaks to cost rather than to selection criteria.

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/closed-world, so the bar is lower, and the description still adds real substance: the data is sourced from job ads, reported as percentiles, sliced by period, and optionally enriched with change-over-time and market benchmarks. The 'advertised, not actual pay' disclosure is the kind of semantic caveat annotations cannot carry. It does not discuss row cardinality or default output shape.

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 'Use for:' trigger list followed by the data description and the key caveat last. The first sentence is a long comma-chained run-on that could be tighter, but nothing is wasted for a 22-parameter 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 22 optional parameters, zero required fields, and no output schema, an agent needs to know what happens when no filters are supplied and at what grain rows are returned — neither is addressed. The description covers what the data means well, but leaves the no-argument default and result granularity to inference.

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 95% across 22 parameters, so the schema already explains SOC/NAICS/role/location ID formats, enums, and defaults. The description only loosely echoes a few of these ('by period', 'optional change over time and market benchmarks') without adding format or interaction rules (e.g., how split interacts with company filters). 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 opening 'Use for:' clause names the exact resource (pay/salary/wages/hourly rate/earnings) and the dimensions it is keyed on (occupation, city/metro/state/country, company). The second sentence pins the actual data product — advertised pay percentiles p10–p90 from job ads — which separates it cleanly from sibling tools like get_postings or account_usage.

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 stated as a list of question shapes the tool answers ('what does a job pay', 'pay trends', 'how pay compares with the market'), which is strong positive guidance. It also adds a decisive scoping caveat — 'Pay is advertised pay, not actual pay' — but never names an alternative tool or states when another sibling should be used instead.

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), so the description is free to spend its words on semantics — and it does: 'Job ads first posted' plus 'Counts are ads, not hires' is exactly the kind of interpretive caveat that prevents an agent from misreporting demand as headcount. It doesn't discuss aggregation limits, revision behavior, or result shape.

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 'Use for:' and then a single sentence specifying the measurement, dimensions, and change option. The scenario list is longer than strictly necessary but each item corresponds to a genuine distinct use case, so little 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 17-parameter read-only analytics query with no output schema, the description conveys what is measured (ads posted, not hires), the unit of period, and the available dimensions. Missing only return-shape hints (row-set-per-breakdown behavior implied by the split parameter) and any note on defaults when no dimension is supplied.

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 17 parameters are individually well documented, so the baseline is 3. The description only restates the analysis dimensions (occupation, company, industry, place, change over time) without adding format or precedence guidance 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 concrete verb+resource: job ads first posted, broken out by period, occupation, company, industry and place, with optional change over time. The 'Use for' framing (hiring, labor demand, labor market conditions) makes the subject matter unmistakable and distinguishable from the pay-oriented sibling get_pay.

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 leading 'Use for:' clause enumerates several concrete question shapes (is hiring rising or falling, where demand for an occupation is growing, which industries/companies are hiring, company strategy via hiring shifts), which tells the agent when to pick this tool. It stops short of naming an explicit alternative (e.g. get_pay 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered; the description adds genuinely new behavior — expected latency ('a few seconds'), that results carry a citation, and the two-step interaction pattern with ask_gwix. It does not say what happens when the occupation/place combination yields no data, which keeps it below 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 the selection rule and sized appropriately for a routing-critical tool. The 'show it to the user immediately / straight away' instruction is stated twice, a small redundancy that costs it a point.

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 enumerating the returned metrics and the citation. Combined with 100% schema coverage and full annotations, an agent has everything needed to select and invoke 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 description coverage is 100%, including ISO-2 country codes and the SOC 2018 occupation_code format, so the schema carries the parameter burden and the baseline of 3 applies. The description hints at the country-wide fallback ('the gap to the national market') but adds no syntax or format 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 — produce a fast summary of advertised pay for an occupation in a place — and enumerates the exact contents (median and middle-half pay, national gap, YoY change, ad volume, citation). It is clearly differentiated from ask_gwix, which is named as the full-report alternative.

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 ('Use first, when a question names a job (and a place or country)') plus an explicit routing rule: show this summary immediately, then call ask_gwix for the full report. Nothing about when to prefer the sibling 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description's only added behavioral fact is 'Free', a cost disclosure that is genuinely useful for choosing this over ask_gwix, but it says nothing about the shape or volume of what comes 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?

A single compact sentence with the subject front-loaded and no filler. The cost note is appended last where it belongs, and nothing could be cut without losing 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 no-argument, non-destructive reference tool with full annotation coverage and no output schema, this is close to sufficient: the agent knows it is a free, safe listing of dimension IDs and their lookups. It stops short of 5 only because it does not hint at the return shape or ordering, which matters slightly when 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The mention of 'ID formats' and 'the lookup for each' does usefully signal what the returned fields will mean for downstream calls.

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 the resource (the dimensions GWIX filters by) and states what it exposes about each: ID formats and a per-dimension lookup. That is concrete enough to know the tool is a static reference listing, but it does not explicitly contrast itself with adjacent reference-style siblings such as lookup, crosswalk, or describe, so an agent must infer which reference surface holds what.

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 only implied: the agent must reason that this is the reference to consult before building a filtered query. The single word 'Free' does give a real selection signal against a metered sibling like ask_gwix, but there is no explicit when-to-use, when-not-to-use, or named 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds two useful behavioral facts: the call is free, and it includes the last complete week. It says nothing about ordering, defaults, or response shape.

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?

One compact sentence, front-loaded with the resource and followed by the granularity parenthetical that carries real information. "Free" is slightly out of place but is short enough not to hurt.

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 3-parameter, no-output-schema tool, the description should at least imply what comes back per period (label plus start/end dates) and how `from`/`to` bound the result. The last-complete-week note helps, but the range behavior is left implicit.

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 67%, and the description meaningfully disambiguates the `type` enum by explaining that "month" means a 4-week month and "quarter" a 13-week quarter — context the schema lacks. However, `from` and `to` remain unexplained beyond their YYYY-MM-DD format, so half the range semantics still require guessing.

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 the resource (period labels and exact dates) and enumerates the period granularities, so an agent knows this returns calendar-period definitions rather than aggregations. It never states a verb ("list"/"returns") and doesn't distinguish itself from list_dimensions, leaving some ambiguity among siblings.

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?

There is no guidance on when to call this versus alternatives such as list_dimensions or account_usage, and no prerequisites or exclusions are stated. Only "Free" hints at a reason to prefer it (no cost), which is weak usage 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value by disclosing the three possible outcomes and the required agent behavior on ambiguity ('ask the user or pick using context'). It stops short of describing how many matches come back or what a match record contains.

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 imperative 'Use first' so the routing decision comes before detail. The second sentence partially re-lists entities already named in the first, which costs some tightness, though it adds postcode, country and industry.

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 9-parameter tool with no output schema, the description carries the important weight: it explains when to call, what the return states mean, and what to do on disambiguation. Remaining gaps are small: no guidance on the general 'q' field versus the typed fields, and no sense of result size.

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 89% schema coverage the baseline is 3, and the description earns above that by grouping parameters into entity families: company (or ticker), place (city, postcode, metro, state, country), job family / sub-job family, and industry. This tells the agent which inputs pair with which 'type'. It doesn't clarify the free-text 'q' parameter or that 'metro' has no dedicated field, leaving a minor gap.

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: turn a name into a GWIX ID, and it immediately names the consuming siblings (get_pay, get_postings). Despite the vague tool name 'lookup', the title and first sentence make the resource and direction of resolution unambiguous.

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 'Use first' sequencing plus 'before asking for statistics' states exactly when to call it, and it names get_pay and get_postings as the alternatives it feeds. The no_match / needs_disambiguation branches tell the agent what to do when resolution fails, which is the other half of usage 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 operation. The description adds that it is free and lists the kinds of guidance returned, but it does not cover error behavior for invalid operation IDs or describe the response shape.

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 definition is a single compact sentence, front-loads the resource type, and uses the parenthetical only for concrete operation examples. Every part contributes to identifying what the guide covers.

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 guide with no output schema, the description sufficiently explains what the guide contains. The remaining gap is minor: it does not state what happens if the operation ID is invalid or how the guide content is structured.

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 has 100% description coverage for the single operation parameter, so the baseline is already adequate. The description goes further by giving multiple operation ID examples, helping the agent understand valid values beyond the schema's single get_pay example.

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 identifies the resource as a context guide for an operation and specifies what it contains: parameters, rules, minimum sample sizes, and result wording. The operation list makes the scope concrete, though it does not explicitly differentiate itself from sibling tools such as ask_gwix or the actual data operations.

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: an agent should call this when it needs guidance about an operation before or instead of calling that operation directly. However, the description does not explicitly say when to use read_guide versus ask_gwix or the operation tools themselves, nor when not to use it.

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