opportunity-exchange

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

No annotations are present, so the description must carry the burden. It mentions tax, housing, utilities, and commuting in the calculation, and references 'meta.evidence' for occupation truth state, but does not elaborate on side effects or data sources.

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 two sentences but the first is somewhat cryptic with a colon. It is concise but could be clearer in structure.

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?

No output schema exists, and the description does not specify the return value format (e.g., per community or aggregated). It mentions 'every Saskatchewan community' but not how the result is structured, leaving the agent with incomplete context.

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 input schema already provides descriptions for both parameters (wage as CAD, occupation as role id). The tool description adds context that occupation models median wage with posting counts and that either parameter can be passed, which adds value 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?

The description explains it computes net disposable income after tax and expenses for Saskatchewan communities, using a wage-vs-cost join. While it clearly states the tool's function, it doesn't explicitly differentiate from siblings like compare_roles or get_wages.

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 mentions passing occupation or wage but provides no guidance on when to use which, nor does it suggest when not to use this tool or compare it to alternatives.

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?

No annotations are present, and the description does not disclose behavioral traits such as read-only nature, required permissions, or rate limits. The action 'compare' implies a read operation, but this is not explicit.

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 a single concise sentence that front-loads the core action and key details, with no unnecessary words.

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 tool with no output schema, the description fails to specify the return format (e.g., comparison table). While the core action is clear, the lack of output details leaves the agent to infer results.

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 covers the 'ids' parameter fully (100%), but the description adds valuable context by listing the specific fields (wages, demand, etc.) used in the comparison, which is not in 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 clearly states the tool compares roles using specific occupational fields, making the purpose evident. However, it does not differentiate from sibling tool 'compare_outcomes', which may perform a similar comparison.

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?

No guidance is provided on when to use this tool versus alternatives like 'compare_outcomes'. There is no mention of prerequisites or 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?

With no annotations, the description carries full burden. It explains the tool returns three-state feasibility and ranked pathways and is request-scoped (no persistence). It lacks details on performance or side effects, but the behavior is adequately disclosed for a read/evaluate tool.

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 two sentences, front-loading the core purpose and key behavioral traits. Every part is essential, with no wasted words.

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 15 parameters and no output schema, the description covers purpose, scope, and general behavior. It lacks details about the return format (e.g., what 'three-state feasibility' means), but overall it is reasonably complete for a complex 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?

Schema description coverage is 100%, so baseline is 3. The description lists many inputs in the first sentence but adds no additional meaning beyond what the schema already provides for individual parameters. No deeper context is given for parameters.

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 evaluates realistic routes into work for a person's credentials and constraints, with a specific verb ('evaluate') and resource ('pathways'). It distinguishes from siblings like 'compare_outcomes' by focusing on feasibility analysis.

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 mentions request-scoped evaluation (constraints never stored), implying one-time use. However, it does not explicitly state when not to use this tool or provide alternatives, missing some guidance for selection among siblings.

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?

No annotations are provided, so the description carries the full burden. It implies a read operation but does not explicitly state side effects, auth requirements, or return format. It adds some context about the data attributes but lacks behavioral details.

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 a single, well-structured sentence. It front-loads the purpose and key attributes, with no wasted words.

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 no output schema and no annotations, the description provides a comprehensive overview of the tool's output and usage context. It covers the essential information needed for an agent to decide when and why to call it.

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 no parameters and 100% schema coverage, the description adds value by explaining what the tool returns (e.g., confidence tier, licence). Baseline 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 clearly states it provides provenance and serving mode for every data source, listing specific attributes like confidence tier, licence, freshness, and validation. It distinguishes itself by covering all data sources, unlike the more specific sibling 'get_source_provenance'.

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 instruction 'Read this before quoting any figure as fact' explicitly tells when to use the tool, though it does not mention alternatives or when not to use. This is sufficient guidance for an AI agent.

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?

No annotations exist, so description must carry full burden. It discloses that the tool returns median price, listings, market velocity, and cost metrics, and that passing municipalityId adds price trend and full ownership model. It does not specify output format or side effects, but the tool is read-only and the behavior is well implied.

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 wasted words. Key information is front-loaded ('Housing market by community: ...') and parameter usage is clearly stated.

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 no output schema, the description lists several output components (median price, listings, market velocity, own-vs-rent cost, plus trend and ownership model when filtered). It covers the main aspects but lacks detail on exact output fields or structure.

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 already describes municipalityId as an optional ID. Description adds value by specifying the extra data (price trend, full ownership model) provided when the parameter is used, beyond the schema's description.

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?

Description clearly states the tool provides housing market data per community (median price, listings, market velocity, own-vs-rent cost). This is distinct from sibling tools like get_rents, get_wages, etc., making its purpose specific and 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?

Description explains when to pass municipalityId (for one community with extra details) and when to omit (for all communities). While it doesn't explicitly compare to siblings like get_rents, the context is clear enough for an agent.

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?

No annotations provided, so the description carries full burden. It discloses suppressed cells are null and unsurveyed centres absent, and data is real from a specific survey. Does not cover auth or rate limits, but adds meaningful behavioral context.

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 succinct sentences with no extraneous words. First sentence defines purpose and data source, second gives usage guidance, third clarifies data quirks. Perfectly front-loaded.

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?

No output schema, but description mentions return fields (average rents by unit type and vacancy rates). Covers key aspects for a tool of moderate complexity; could mention response format or limitations but adequate.

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%, but the description adds value by explaining 'centre' is a cmhcCode from a previous call and 'province' can be SGC or postal abbreviation, which goes beyond the schema 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 average rents by unit type and vacancy rates from CMHC data, with specific geographic scoping. It distinguishes itself from sibling tools like get_real_estate by focusing on rental market data from a specific survey.

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 instructions on how to use parameters: pass province for provincial data, centre code for a single centre, or neither for national overview. No explicit alternatives or when-not-to-use, but the guidance is clear and practical.

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?

With no annotations, the description provides detailed behavioral context about returned data (market figures, entry requirements, working conditions, training programs, per-community outcomes). It discloses what the tool returns but omits potential side effects or auth needs, though the read nature is implied.

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 a single, front-loaded sentence that efficiently lists all key output categories without redundancy or 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?

Given the single parameter and no output schema, the description covers the tool's purpose and output thoroughly. Minor omission: does not specify output format (e.g., structured JSON), but this is not critical for a retrieval 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?

While schema coverage is 100% and baseline is 3, the description adds meaningful context by explaining that 'id' comes from list_roles, aiding parameter selection beyond the schema description.

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 uses a specific verb-resource structure ('One occupation in full') and lists explicit data categories, clearly distinguishing from sibling tools like list_roles (list only) or compare_roles (comparison).

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 use for fetching full details of a single role, but does not explicitly state when to use this vs. other tools (e.g., for exploration vs. comparison) or provide exclusion 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?

No annotations are provided, so the description must disclose behavior. It lists the output components, but it does not specify safety (e.g., read-only) or any side effects. Adequate for a simple retrieval tool.

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 extremely concise, consisting of a single phrase that conveys the essence. Every word contributes meaning with no redundancy, making it efficient for an AI agent.

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 simplicity (1 parameter, no output schema), the description adequately covers what the tool returns. For a basic lookup, it is complete, though it lacks details on error handling or edge cases.

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% for the single parameter. The tool description adds context by specifying that the id comes from list_sectors, which helps the agent understand the parameter's provenance 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?

The description clearly states it returns a single sector with specific details (occupations, vacancies, notable employers). The verb 'get' and resource 'sector' are precise, and it distinguishes from list_sectors (which lists all sectors).

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 by mentioning the parameter comes from list_sectors, but it does not explicitly state when to use this tool vs alternatives like get_role or get_trade_overview. No guidance on prerequisites or 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool can return a single entry or the full registry based on the id parameter, and lists the data fields. However, it does not mention side effects, authentication requirements, rate limits, or performance characteristics. For a read-only tool, this is adequate but not exceptional.

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, well-structured sentence that front-loads the purpose and lists all relevant details. No extraneous words; every part is necessary.

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 no output schema, the description lists the specific fields returned (serving mode, upstream, licence, freshness, validation, readiness). It also explains the two modes of operation. It is nearly complete, though it could clarify the output structure when returning the full registry (e.g., an array of objects).

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 description adds meaning beyond the schema by explaining that omitting the id returns the complete registry, and that the id comes from get_data_sources. The schema provides 100% coverage for the single optional parameter, but the description enriches the semantics with usage context.

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 uses a specific action ('Get') and resource ('source provenance'), and clearly distinguishes between fetching a single entry or the full registry. It lists the specific fields retrieved (serving mode, upstream, etc.), aligning with the tool's name and differentiating it from siblings like get_data_sources which likely lists sources without provenance details.

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 when provenance details are needed, but does not explicitly state when to use this tool versus alternatives like get_data_sources. No exclusion criteria or alternative recommendations are provided, leaving the agent to infer context from the tool's purpose.

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?

No annotations are provided, so the description must disclose behavioral traits. It does not state whether the tool is read-only, the data freshness, or any side effects. The lack of parameters implies a fixed query, but behaviors like rate limits or cache behavior are unaddressed.

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 remarkably concise: two short sentences that front-load the purpose and include data sources. Every word is necessary and there is no fluff.

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 no output schema, the description partially explains the return value: provincial exports and grain deliveries. However, it omits details like time range, aggregation level, or how results are structured. For a zero-param data retrieval tool, it is minimally acceptable but not fully 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?

There are zero parameters, so the schema coverage is trivially 100%. The description does not need to explain parameters but adds value by describing the data content. Baseline 3 is appropriate as no parameter info is missing.

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?

Description clearly states the tool provides Saskatchewan provincial exports by NAPCS section and producer grain deliveries by delivery point, citing real published data sources. This distinguishes it from sibling tools focused on roles, comparisons, or real estate, though it could be more specific about the data format or time period.

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?

No guidance on when to use this tool versus alternatives like 'get_data_sources'. The description does not mention prerequisites, contexts, or exclusions, leaving the agent to infer based on the data 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?

With no annotations, the description carries full burden. It discloses data sources (LFS, JVWS), real data nature, grouping levels, and that wage medians are group-level. Lacks discussion of update frequency or rate limits but sufficient for a read-only data retrieval.

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 a single dense paragraph but effectively front-loaded with main purpose. It could be more structured with bullet points, but every sentence adds value without redundancy.

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 no output schema, the description explains what types of data are returned (medians, averages, grouping names). For a simple retrieval tool with two optional parameters, the description is complete and leaves no major ambiguity.

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 description adds significant context: explains the effect of passing each parameter (noc, province) and their acceptable formats (e.g., SGC code, postal abbreviation, 'canada'). Goes beyond the schema description.

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 specifies the tool provides wages and vacancies from Statistics Canada LFS and JVWS, with detail on grouping (occupation group, province, NOC unit group). It distinguishes itself from sibling tools like compare_outcomes or list_noc_groups.

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 explains parameter combinations: pass noc for one unit group across geographies, province for one geography, both for one cell, neither for national overview. This provides clear when-to-use guidance, despite no explicit alternatives listed.

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?

No annotations provided, so the description must fully disclose behavior. It mentions suppression of small cohorts and null pressure meaning, but lacks details on whether it is read-only, destructive, or requires authentication.

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 front-loaded sentences with no wasted words. Every sentence adds 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?

Given the lack of parameters and output schema, the description provides the core logic but is cryptic. It does not explain the output format or full behavior, leaving some ambiguity.

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?

There are no parameters, so baseline 4 applies. The description does not need to add parameter meaning, and it effectively explains the tool's function.

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 aggregates vacancies gated by credentials, which differentiates it from sibling tools like compare_outcomes or list_roles. However, jargon like 'gated' and 'pressure' slightly reduces clarity.

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?

No explicit guidance on when to use this tool vs alternatives. The description explains what it does but not the context or prerequisites.

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?

No annotations are provided, so the description carries burden. While the operation is clearly read-only (no parameters), the description does not explicitly state non-destructive behavior or any other traits beyond listing contents.

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, concise and front-loaded: first sentence describes content, second describes usage. No wasted words.

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 description covers the output fields (bilingual titles, TEER tiers, coverage flags) and purpose. With no output schema, it is adequate for a simple list, though it omits potential details like sorting or pagination.

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?

No parameters exist (0 params), so baseline 4 applies. The description adds no parameter info because none are needed.

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 lists all NOC 2021 unit groups with specific fields. The verb 'list' and resource 'noc_groups' are specific, but it does not distinguish from sibling list tools like list_roles or list_sectors.

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?

Provides a clear use case ('Use to map any Canadian occupation to its code') but does not mention when not to use or suggest alternatives.

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?

No annotations provided, so description carries the burden. It states it returns a catalogue with specific fields but does not disclose any behavioral traits such as pagination, ordering, or whether it requires authentication. Given the simplicity (list all roles), the description is adequate but lacks extra context.

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, no redundancy. Front-loaded with purpose and content summary. Every word earns its place.

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?

Description explicitly lists all return fields, fulfilling the role of output schema. It also provides usage hint ('start here'). Given no output schema, this is complete for a list-all-roles tool with 0 parameters.

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?

No parameters in schema (baseline 4). Description adds value by listing the output fields, which helps understand what the list contains, compensating for lack of output schema. No param details needed.

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?

Description clearly specifies verb 'list' and resource 'roles' (occupations). It lists the exact fields returned: id, title, NOC code, sector, hourly wage, demand score. This distinguishes it from siblings like get_role (specific role) or compare_roles (comparison).

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?

Description says 'Start here to find role ids,' indicating this is the entry point for obtaining role identifiers before using other tools. It provides clear context but does not explicitly state when not to use it or mention alternatives beyond implication.

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?

With no annotations, the description minimally covers behavior by listing the data fields returned. It implicitly suggests a read-only operation, but lacks explicit statements about scope (e.g., 'all sectors'), no side effects, or any limitations. For a zero-parameter list tool, this is adequate but not thorough.

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 extremely concise—a single fragment—yet conveys the essential information. Every word is necessary, and there is no redundancy or 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?

Given the tool's simplicity (no parameters, no output schema), the description provides sufficient context by enumerating the data fields. It could be slightly improved by explicitly stating that it returns data for all sectors, but overall it is complete enough for a basic list 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?

There are no parameters, and the schema coverage is 100%. The description does not need to add parameter-specific information, so it meets the baseline expectation for this dimension.

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 indicates that the tool provides rollup data for sectors, including specific metrics like vacancies and median wage. It distinguishes from sibling tools like 'get_sector' (likely for a single sector) and 'list_roles' (which lists roles, not sectors). However, it could more explicitly state that it lists all sectors.

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?

No guidance is provided on when to use this tool versus alternatives such as 'get_sector' or other list tools. The description does not mention prerequisites, context, or 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?

No annotations are provided, so the description carries the burden. It discloses the ranking behavior but lacks details on output format, data freshness, or operational traits (e.g., read-only). The description is adequate but minimal.

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?

Single sentence, front-loaded with key verb and object, no wasted words. Ideal length for quick comprehension.

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 3 parameters, no output schema, and no annotations, the description covers purpose and parameter constraints but omits behavioral details like output format, pagination, or data sources. Adequate but not fully self-contained.

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%, but the description adds critical context: the mutual exclusivity of occupation and wage, and the ranking metric 'monthly discretionary income'. This goes beyond the schema's field 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?

Description clearly states verb 'rank', resource 'Saskatchewan communities', metric 'monthly discretionary income', and constraint 'exactly one role or explicit hourly wage'. Distinguishes from sibling tools like compare_outcomes or get_real_estate.

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 explicitly constrains usage to one role or wage, which helps agents choose this tool. However, it does not mention when not to use it or suggest alternative tools for broader queries.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It describes a search operation but does not mention whether results are paginated, ordered, or if there are rate limits. Basic behavioral traits are omitted.

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, well-structured sentence that front-loads the action ('Search') and lists key filter dimensions. No unnecessary words or repetition.

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 search tool with no output schema and straightforward parameters, the description is mostly complete. However, it lacks mention of default limit (25) or pagination behavior, which would be helpful for an agent.

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 schema already documents each parameter well. The description merely lists filters (name, municipality, sector, hiring) without adding value beyond the schema. Baseline score of 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 the action ('Search'), the resource ('public employer directory'), and the filter criteria (name, municipality, sector group, hiring status). It directly corresponds to the tool name and distinguishes it from siblings like search_jobs.

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?

No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites or exclusions mentioned. Sibling tools like search_jobs or get_role exist, but the description does not clarify how this tool fits.

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?

With no annotations, the description carries full responsibility. It discloses the sorting order (newest first) and warns about synthetic preview records, which is valuable behavioral context. It does not cover auth, rate limits, or side effects.

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 concise sentences with no filler. The first sentence states purpose, and the next two add critical data quality caveats. Every sentence earns its place.

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?

Despite 10 parameters and no output schema, the description only covers sorting and data quality. It does not explain return fields, pagination behavior, or multi-parameter interactions, leaving significant gaps for an agent to understand the tool's full behavior.

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 adds no additional parameter semantics beyond 'filterable', so it does not improve understanding of parameters beyond what the schema provides.

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 returns job postings sorted newest first with filtering, which is a specific verb-resource combination. It distinguishes from sibling tools by focusing on jobs, though it does not explicitly contrast with similar search tools.

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 use this tool vs. alternatives like 'search_employers'. The description only implies usage for job searches but lacks explicit context or exclusion criteria.

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