NordicContacts

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

Goes well beyond the readOnly/destructive annotations: it discloses billing behavior ('free to call; does not consume account balance'), the always-on non-disableable exclusion list, the CUSTOMER_LIST_REQUIRED precondition, and the pagination/return behavior ('does not support pagination and always returns a total count'). This is exactly the operational context an agent needs before calling.

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 distinction and billing note, then handles filter rules and customerListMode. Dense and mostly waste-free, though the customerListMode explanation partially restates 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 25-parameter tool with nested objects and no output schema, it covers the high-risk constraints (no pagination, returns only a count, billing, exclusion-list behavior, taxonomy name rules). Remaining filter parameters are left to the fully-populated schema, which is reasonable.

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 adds interaction semantics the schema states thinly: the webshopStatus/webshopPlatforms dependency and the canonical-vs-localized taxonomy constraint for keywordCategoryFilter ('pass only canonical returned name values; never pass localized labels or raw keywords'). It does not walk the many other filters, but the schema does.

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+resource (count matching companies for segment filters) and immediately differentiates from the listing siblings via 'without loading company/contact rows.' An agent can tell this is the count-only path versus list_company_segment without opening a 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 explicit when-to-use ('how many companies' questions) and conditional validity rules (webshopPlatforms only valid with webshopStatus 'identified' or omitted; customerListMode exclude/limit require an active list). It never names list_company_segment as the alternative it is contrasted against, leaving the routing to the reader.

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?

Adds substantial behavior beyond the readOnly/non-destructive annotations: it is free and consumes no balance, always applies the account exclusion list, requires an active customer list for exclude/limit modes, and does not paginate (always returns a total). These are real operational traits 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?

Front-loads the core purpose and expected question type, then layers constraints. It is dense and slightly repetitive with the schema (customerListMode is restated), but each sentence carries actionable guidance rather than 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?

For a 25-parameter, nested-object tool with no output schema, the description covers the return shape ('always returns a total count', no pagination), billing cost, and key filter interactions. Remaining ambiguity (e.g. count upper bounds or caching) is minor given the rich 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 the schema already documents most fields, but the description adds cross-parameter semantics (webshopPlatforms only valid with webshopStatus 'identified'), the canonical-name constraint for taxonomy values, and the automatic exclusion-list behavior. It consolidates multi-field interactions usefully, though much overlaps 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 'Count' plus the resource 'matching contacts for segment filters', and immediately distinguishes the tool from the list variant with 'without loading contact rows'. An agent knows exactly what this does versus list_contact_segment.

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 a clear use case ('how many contacts questions') and routes taxonomy lookups to list_keyword_categories and search_keyword_subcategories. It does not explicitly contrast with count_company_segment or spell out when NOT to use this tool, so routing guidance is clear but not exhaustive.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the shape of what comes back (names, operation groups, usage hints), which matters because there is no output schema.

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 tightly packed sentence with the tool's purpose and its return framing front-loaded. No filler, though the phrasing is somewhat dense with three separate noun phrases.

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 partially compensates by sketching return contents, and the read-only annotations remove the need to explain side effects. An agent has enough to invoke this correctly, though permissions or rate/size limits are unstated.

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

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

The single parameter includeExamples is documented at 100% coverage in the schema, including its default. The description does not mention it or add syntax beyond the schema, so the baseline 3 for high coverage 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?

States a specific verb ("Describe") and resource ("MCP tool capabilities") and frames the outcome as names, operation groups, and usage hints. It implicitly contrasts itself with the business endpoints in the sibling list (find_*, list_*, count_*), though it does not name a specific sibling.

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 clear timing guidance: call it to "self-discover available routes before calling business endpoints." This gives an agent a concrete trigger condition, but it names no explicit alternative or exclusion case, so it falls short of full 5-level routing 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 only declare a safe read, but the description adds material behavior: precedence order among identifiers, countryId still constraining the lookup, the shared subscription balance being consumed, a minimum cost of 1 unit, and the exact cost rules for resolved vs ambiguous results. Return shapes (resolvedCompany with match score/type vs ranked candidates with ambiguity detection) are also disclosed.

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 lookup keys and an inline example, and every sentence carries routing, precedence, return-shape, or cost information. It is dense and long, with the cost sentences arriving late, but nothing is 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?

For a 6-parameter lookup tool with no output schema, the description supplies the missing return semantics (resolved match vs ranked candidates, ambiguity detection) plus billing behavior. An agent has everything needed to call it correctly and predict the outcome.

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 already 100%, and much of the description restates it, but it adds genuine interpretation: companyId is the internal ID appearing as id/companyId, not a registration ID, and it takes precedence over the other identifiers. The precedence and cost-per-parameter implications go 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 (find) and resource (companies) plus the four identifier types it accepts, then explicitly contrasts itself with resolve_company_by_domain and list_company_segment. An agent can distinguish it from every sibling without opening a 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 explicit routing: domain-only lookups go to resolve_company_by_domain, bulk retrieval to list_company_segment, and this tool is scoped to identity resolution of 1-3 matches. It also states when to use the domain field here versus elsewhere.

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?

Goes well beyond the readOnly/non-destructive/closed-world annotations by disclosing the billing model: it draws on the shared account subscription balance (same pool as Excel exports and REST API), with monthly included units consumed before prepaid top-ups. It also caps the result set at one row, which annotations cannot convey.

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 purpose and row-limit are correctly front-loaded, but the cost section is repetitive and slightly self-undermining: 'always costs at least 1 unit' followed by 'costs exactly 1 contact unit per completed call' leaves the agent unsure whether a call can cost more than one unit. Two sentences could be collapsed into one.

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 lookup with no output schema, the description covers input precondition, result cardinality, and cost. The notable gap is the not-found case: since cost is emphasized, an agent needs to know whether a no-match call still charges a unit and whether it returns an empty result or an error.

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 single parameter already carries a description plus format and regex pattern, so the schema does the heavy lifting. The description adds only that the email must be 'known', which is marginal beyond what the schema provides; 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?

States a specific verb and resource ('Find one individual contact'), the exact input class ('known email address'), and the result shape ('Always returns at most 1 row'). This cleanly separates it from the bulk listing siblings like list_company_contacts and from the company-side analog resolve_company_by_domain.

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 precondition for use is explicit: you must already have the email address, which frames it as a resolution/lookup tool rather than a search tool. It does not state when NOT to use it or name an alternative for partial-name or fuzzy contact 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 only cover the read-only safety profile, yet the description adds a full cost model (shared subscription balance, included then prepaid units, minimum 1 unit per completed call, 1 unit per returned contact), deterministic pagination semantics, and the isAmbiguous/candidates fallback behavior. These are exactly the behavioral traits an agent cannot infer from structured fields.

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 return shape, then layers ambiguity handling, an example, a cost tip, and the billing rule. Every sentence earns its place, though the cost discussion runs three sentences 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?

With no output schema, the description carries the full burden and does so: it describes the resolvedCompany payload, the omitted candidates field, the compact contact row shape, the ambiguity signal, pagination, and billing. An agent has everything needed to invoke and interpret the call.

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 real meaning: the companyId/businessId/companyName fallback relationship, the limit+offset pairing for deterministic paging, and the sample-fetch use of a small limit. It does not add much for countryId or contactInfoFilter beyond the schema, keeping it just under a 5.

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 ('Retrieve contacts that belong to one company') and immediately scopes the return shape (resolvedCompany plus compact contact rows). This clearly separates it from siblings like find_companies and list_contact_segment, which operate across companies or segments rather than within a single company.

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 guidance on the ambiguous-name case (re-call with companyId or businessId) and on using a small limit for sample fetches, plus a worked example call. It never explicitly says when to prefer this over sibling tools such as list_contact_segment or find_contact_by_email, so it falls short of full alternative routing.

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 only cover the safety profile (readOnly/non-destructive), but the description discloses the cost model (shared subscription balance, minimum 1 unit per call, 1 unit per company row), deterministic pagination, and the fact that the account exclusion list always applies and cannot be disabled. These are materially important traits an agent cannot infer from the schema.

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?

It is long, but for a 27-parameter nested-object tool most sentences earn their place and the purpose is front-loaded. Minor redundancy where customerListMode behavior is restated nearly verbatim from the schema, which could be trimmed.

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 still characterizes the return payload (paginated, deterministically ordered rows with hasWebshop/webshopPlatform/targetMarket attributes) and covers cost, auth/setup prerequisites, and filter interactions. Nothing an agent needs to call this correctly is missing.

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 schema carries the per-parameter burden and baseline is 3. The description nonetheless adds cross-parameter semantics the schema cannot express: keyword filters must use canonical returned names (never localized labels or raw keywords) and that keywordCategoryFilter operates on classified taxonomy rather than raw 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 (List) and resource (companies matching segment criteria), then enumerates the filter surface (country, industry, size, new contacts, webshop, target market). It explicitly differentiates from the sibling count_company_segment at the end of the description.

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?

Names alternatives and the conditions that select them: count_company_segment for count-only questions, list_keyword_categories for broad categories, search_keyword_subcategories for specific activities. It also states when webshopPlatforms is valid and requires customer-list setup for exclude/limit modes.

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?

Goes well beyond the readOnly/non-destructive annotations by disclosing billing behavior (consumes shared subscription balance, minimum 1 unit per call, 1 unit per returned row), determinism, pagination support, the always-on account exclusion list, and the CUSTOMER_LIST_REQUIRED failure mode. These are material operational facts an agent cannot infer from structured fields.

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?

Dense but well-ordered: purpose first, then cost/return semantics, then filter constraints, then routing to siblings, closing with a concrete example. A few statements (customerListMode, webshopPlatforms validity) restate schema text verbatim and could be trimmed, so it is efficient rather than lean.

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 27-parameter tool with no output schema, the description supplies the missing pieces: what each returned row contains, what response meta includes (companyCount), cost model, and how to reach sibling discovery tools for enum values. Nothing essential for a correct call is left unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics and discovery routing not fully spelled out in the schema (taxonomy level usage, canonical-vs-localized name rule, customer-list mode trade-offs) plus a worked example call. Some of this duplicates schema text, keeping it below a 5.

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 ('Return a filtered contact segment'), scopes it as contact-level output, and explicitly contrasts with siblings: find_companies/list_company_segment for full company details and count_contact_segment for count-only questions. It also enumerates the returned row shape (person fields, employer context, classification attributes), so an agent knows exactly what this returns.

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?

Names alternatives and the conditions that select them: count_contact_segment for count-only questions, find_companies/list_company_segment for full company details, list_keyword_categories vs search_keyword_subcategories for taxonomy level. It also states hard validity constraints (webshopPlatforms only with webshopStatus 'identified' or omitted; exclude/limit require an active customer list).

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful cost context ('Free to call; does not consume account balance'), which goes beyond annotations. However, it doesn't describe pagination behavior for the limit parameter or how results are ordered.

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 the core purpose and the specific values, followed by usage timing and cost note. Every clause earns its place with no 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?

For a simple, read-only lookup tool with a fully documented schema, the description covers purpose, context, and cost. Minor gaps like return ordering or the absence of an output schema note are acceptable given the tool's simplicity.

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 clear descriptions for both limit (defaults to 200, max 500) and search (case-insensitive name filter). The description adds no parameter-specific detail beyond the schema, so the baseline of 3 is correct.

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 states a specific verb and resource ('List available supported countries') and even enumerates the known values (Finland, Sweden, Estonia) with their purpose (IDs for countryId filters). This distinguishes it from lookup siblings like list_industries or list_job_functions.

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 clearly states when to use it ('when building geography-based segments before calling segment/count tools'), naming the downstream tools. It doesn't give explicit exclusions, but the 'before segment/count tools' framing establishes the workflow context well.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds meaningful non-annotation behavior: prefix-matching semantics of the returned codes, pagination via offset/limit, and the cost profile ('Free to call; does not consume account 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?

Front-loaded with purpose, then rules, examples, and cost. It is dense and slightly long, but nearly every sentence carries actionable information and none 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 no output schema, the description carries the return-shape burden and does so by specifying string IDs and an example. It also covers the pagination, search, and cost concerns an agent needs before calling.

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 real value: it explains the downstream purpose of countryId, gives concrete code examples ('62100' = Computer programming in Finland), and shows search terms and offset stepping that go beyond the schema's field docs.

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+resource ('List detailed industry codes for a specific country') and immediately scopes it by country classification system. It is clearly distinguishable from siblings like list_industry_groups and list_countries through the classification-system detail.

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?

Explains when to use it (to obtain IDs required for the industryCodes filter on segment tools) and gives a hard rule ('Always pass countryId matching the country you are segmenting'). It stops short of explicitly naming list_industry_groups as the alternative for grouped views, so it's clear context without full alternative routing.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new operational context — 'Free to call; does not consume account balance' — which an agent needs when choosing between candidate calls. It does not describe pagination or default page size behavior, though the schema covers limit.

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 short sentences, front-loaded with the resource and the reason for calling, with the cost note last. No filler and nothing that restates the tool name.

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 usefully sketches the return shape (groups plus their IDs) and gives an example. It does not mention that results may be large or paginated via limit, but for a simple free lookup this is nearly 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 description coverage is 100%, with both limit and search fully documented in the schema, so the baseline is 3. The description adds no filter syntax, matching rules, or search behavior beyond what the schema already states.

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 (List) and resource (high-level industry groups) and explains what the returned IDs are for ('use in industryGroupIds filters'), with a concrete example value. The implicit contrast with the finer-grained list_industries sibling is present via 'high-level' but never made explicit.

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

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

Gives a clear condition: 'Use when broad sector filtering is needed.' That tells the agent when this tool fits, but it does not name the alternative (list_industries) or state when to prefer that one instead, so the routing decision is left partly 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context not present in structured fields: 'Free to call; does not consume account balance,' which matters for an agent budgeting calls.

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 tight sentences: purpose and output first, then the specificity clarification, then the cost note. No filler, and the most important information (what it returns and why) is 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?

For a simple, zero-required-param read tool with a fully documented schema and no output schema, the description covers purpose, category semantics, and cost. Minor gaps like ordering or pagination behavior are handled by the schema's limit parameter, so nothing essential is missing.

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 limit and search are already fully documented in the schema. The description adds no syntax or format detail beyond that, so the 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?

States a specific verb and resource ('List available job functions with IDs') and explains the downstream purpose (use in jobFunctionIds filters). It also distinguishes itself conceptually from the related sibling category by noting these are 'typically more specific than main responsibility areas.'

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?

Explains the context in which the output is consumed ('IDs to use in jobFunctionIds filters') and positions it relative to main responsibility areas, giving the agent a clear sense of when this list is the right one. It stops short of naming an explicit alternative tool to call 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 cover the read-only/non-destructive profile, and the description adds real behavioral context beyond them: it excludes internal classification keywords from the result, and it states the call is free and does not consume account balance. It also discloses what is returned (canonical names plus Finnish/Swedish/English labels).

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 what is returned, then when to call it, then the filter-usage caveat, then the exclusions and cost note. Every sentence carries actionable information with no 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?

There is no output schema, so the description carries the burden of describing results, and it does so (taxonomy level, canonical names, three label languages). For a zero-parameter lookup with annotations already covering safety, nothing an agent needs is missing.

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 the schema has nothing to document and 4 is the baseline. The description does usefully explain how a returned name feeds keywordCategoryFilter with level "main", but that concerns other tools rather than this one's inputs.

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 (List) and resource (customer-facing company keyword categories) and pins down the scope as 'the main taxonomy level,' with the three label languages named. An agent can distinguish this from search_keyword_subcategories 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?

Gives a clear triggering condition: user asks for a broad business category, or you need to narrow a subcategory search. It also warns against using a localized label as the filter name. The sibling search_keyword_subcategories is only alluded to ('subcategory search') rather than named, so routing is slightly less explicit than a 5.

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, openWorldHint=false, destructiveHint=false, so the safety profile is known. The description adds the non-obvious behavioral fact that the call is free and does not consume account balance, which is valuable purchasing-related context an agent could not infer from annotations. It doesn't describe pagination or result ordering, but that is a minor gap.

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 tight sentences, zero waste. The core purpose and downstream use case are front-loaded, with the cost note trailing. 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?

For a simple read-only lookup list with full schema coverage and no output schema, the description covers purpose, usage context, and cost behavior sufficiently. The main omission is any indication of result format or ordering, but this is minor given the tool's simplicity.

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 both parameters (limit, search) are fully documented in the schema including defaults and bounds. The description adds no parameter-level detail beyond what the schema provides, so 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?

States a specific verb and resource ('List available main responsibility areas'), explains they carry IDs for filtering, and gives examples (Sales, IT, Marketing). It is clearly distinguishable from siblings like list_industries or list_job_functions by its functional-role scope.

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 says when to use it ('Use for broad functional-role filtering.') and how the returned IDs feed into 'mainResponsibilityAreaIds filters', making the downstream usage pattern concrete. It also states the cost condition ('Free to call').

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 cover the safety profile (readOnlyHint, destructiveHint false), and the description adds substantial behavior beyond them: exact-match-only semantics, the single-match vs. ambiguous-candidate vs. empty-result outcomes with field names, and a detailed cost model (shared subscription balance, minimum 1 unit, 1 unit per returned company). This is unusually rich disclosure for a read 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?

Front-loaded with the core purpose and routing, then return semantics, then cost. Dense but every clause carries information. Slightly long due to the cost-model sentence and example, 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 no output schema, the description compensates by describing return shape (resolvedCompany set, candidates omitted, isAmbiguous flag), empty-result behavior, and billing impact. Nothing an agent needs to invoke it correctly is missing.

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 all three parameters are already documented in the schema. The description adds only a usage example ('domain: dynava.com, limit: 5') and no syntax or format detail beyond it, so baseline 3 is appropriate.

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

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

States a specific verb+resource (resolve companies by exact website domain) and explicitly scopes it as a direct exact-match lookup. It names the sibling find_companies and the condition that differentiates them, so an agent can distinguish it from alternatives 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?

Explicitly states when to use ('verified, exact domain... direct lookup') and when not to ('if you need ranking across multiple criteria or have ambiguous input, use find_companies instead'). The alternative and the selecting condition are both named.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful non-obvious traits beyond the annotations: it does not return raw keyword text, and it is free to call and does not consume account balance. It does not, however, address pagination behavior despite exposing limit/offset.

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 dense but front-loaded, leading with what the tool searches and what terms it accepts before moving to narrowing options and caveats. Every sentence carries information, though the workflow sentence about keywordCategoryFilter and level "sub" is a slight expansion beyond the tool's own boundary.

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 telling the agent what is and is not returned (names suitable for keywordCategoryFilter, no raw keyword text) and by covering cost. What remains thin is pagination and result-shape detail, which the agent would have to infer from the limit/offset 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by clarifying the interaction between search and mainCategories ('mainCategories restrict discovery only; do not add them to the segment filter unless the user also requested those broad categories'). This disambiguates a genuinely easy-to-misuse parameter relationship.

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 ('Search') and resource ('customer-facing company keyword subcategories') and immediately notes the multilingual matching capability. It is clearly distinguishable from the sibling list_keyword_categories, which supplies the mainCategories input rather than the subcategory results.

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 explicit when-to-use guidance ('Use search for a specific business activity such as "sopimusvalmistus"') and names the alternative input path (mainCategories from list_keyword_categories) for ambiguous or broad searches. It also prescribes the downstream workflow: copy the returned name into keywordCategoryFilter with level "sub".

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuinely useful context beyond that: it discloses the return payload categories and flags that the quota/subscription portion is scoped to the authenticated account.

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 sentence with zero filler, front-loaded on the verb and listing the four payload categories in priority order. Every clause 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?

With no parameters and no output schema, the description carries the burden of describing the response, and it does so by naming the four data categories returned. It is close to sufficient; minor gaps remain about whether these are separate sections, formatting, or how quota values are expressed.

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, which sets the baseline at 4. Nothing in the schema needs clarifying, and the description correctly spends no words on inputs.

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 ('Return') and enumerates exactly what is returned: pricing, setup steps, multi-user policy, and account subscription/quota status. This clearly distinguishes it from every sibling (which are all list/find/count lookups over company, contact, or taxonomy data), though it never names an alternative to route against.

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 by the content list — an agent can infer it should call this when it needs pricing, onboarding steps, or the account's quota/subscription state. There is no explicit when-to-use statement, no preconditions, and no mention of alternatives (e.g., describe_tools) for related information.

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