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

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces this with 'read-only' and 'never writes.' It adds useful behavioral context by stating the data is shared reference data and by showing a concrete usage example, going slightly beyond the annotation-only signal without contradicting it.

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 well-structured and front-loaded with the tool's purpose, followed by workflow, an example, and a safety note. The only minor redundancy is repeating 'read-only' and 'never writes' in the final sentence, but overall 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?

Given the output schema and complete input schema, the description supplies the missing context: how this tool fits into the broader Bolagsanalys workflow, what kind of data it operates on, and how to filter results. An agent has enough information to select and invoke this tool correctly without further inference.

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

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

Schema coverage is 100%, so the baseline is already strong. The description adds extra meaning by providing a concrete example combining `nameContains` and `group`, and by explaining how the result's `parameterCode` is consumed downstream, which helps an agent understand the parameter's role in a larger workflow.

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

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

The description clearly identifies the tool as a read-only parameter discovery endpoint: it finds financial parameters by name fragment or group and returns their code, English name, group, and description. It also distinguishes itself from data-retrieval tools by noting its output feeds `bolagsanalys_get_data`.

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 gives explicit workflow guidance: use this tool to resolve `parameterCode` for `bolagsanalys_get_data`, with `companyId` coming from `bolagsanalys_list_companies`. It does not explicitly discuss when not to use search-related siblings, but the chaining context is clear and actionable.

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, and the description reinforces this with 'read-only — never writes.' It adds a useful behavioral detail ('every row keeps its companyId and parameterCode') and clarifies quarter values are packed quarters, not calendar dates. No contradiction with annotations; with readOnlyHint already present, the added behavioral disclosure is adequate but not extensive.

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 well-structured: purpose, optional narrowing, parameter provenance, quarter-format warning, and an example. Minor redundancy ('optionally' repeated; read-only stated twice), but every sentence earns its place and the key clarification 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?

With an output schema present, the description doesn't need to detail return values. It explains parameter origin, quarter-format pitfalls, and the all-companies behavior (omitting companyId for ranking/aggregation). It could mention pagination more explicitly, but the parameter descriptions cover that.

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 good field descriptions, so the baseline is 3. The description adds meaningful above-schema semantics: the quarter format ('2025Q1' vs '20251') with an explicit warning that these are quarters not dates, the provenance of companyId and parameterCode, and a full example. This justifies a 4.

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 ('Fetch quarterly figures') and a clear resource ('Bolagsanalys data'), distinguishing it from sibling tools like bolagsanalys_search_data. Also names the companion tools that supply valid IDs, so an agent knows exactly what this tool does and how it fits.

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 clear usage context: pass companyId from bolagsanalys_list_companies, optionally narrow by parameterCode from bolagsanalys_find_parameter Joseph and quarter range. It does not explicitly state when not to use it versus bolagsanalys_search_data, but the flow is strongly implied by cross-tool provenance.

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 and openWorldHint=true, so the safety profile is covered. The description adds valuable context beyond the annotations: it is reference data shared across all tenants and 'never writes or ingests', which reinforces what an agent can rely on. No contradictory or missing critical behavior is apparent given the read-only nature.

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 compact, front-loaded with the read-only safety indicator and the core search action, then enriched with the flow context and a concrete example. Every sentence contributes meaningful information with no filler or redundant restatement of 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?

Given the output schema exists and annotations cover read-only/open-world behavior, the description completes the picture with the Bolagsanalys flow position, the use of the returned companyId, and an illustrative query example. Nothing an agent needs to invoke this tool 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 the schema already documents all five parameters in detail. The description adds a useful semantic grouping ('by name fragment or country code') and a concrete example (nameContains 'Volvo', countryCode 'SE'), but it does not need to compensate for any schema gap. 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?

The description states a specific verb ('Search'), a precise resource ('Sedis's catalog of listed companies'), and the two filter dimensions (name fragment, country code). It also distinguishes itself from sibling bolagsanalys_get_data by positioning itself as the first step of the flow, so an agent can tell them apart without opening schemas.

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

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

The description gives clear contextual guidance: it is the FIRST step of the Bolagsanalys flow and the returned companyId is meant to be passed to bolagsanalys_get_data. It does not explicitly enumerate when to avoid this tool in favor of siblings like bolagsanalys_search_data, but the flow-level instruction is strong 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?

Beyond readOnlyHint/openWorldHint, it warns quarter bounds are packed quarter ids, not calendar dates; discloses the 50 cap is rejected; and specifies the response envelope and that rows keep companyId and parameterCode. No contradiction with the read-only annotation.

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?

Four dense sentences, with read-only and purpose front-loaded; each sentence adds a distinct fact (scope, alternative route, quarter encoding, cap, return behavior). 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 10-parameter batch tool, the description covers selection criteria, sourcing of identifiers, quarter encoding, hard cap, and return shape; pagination/sort are already documented in the schema and output schema exists. Everything an agent needs to invoke correctly is provided.

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 covers 100% of parameters, so baseline is 3; description adds real value by sourcing companyIds from bolagsanalys_list_companies, parameterCode from bolagsanalys_find_parameter, and clarifying quarterId/fromDate/toDate use packed quarter ids such as '20251'/'2025Q1'. It does not repeat page/count semantics, but the schema already documents those.

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 states precise verb-resource: 'Fetch quarterly figures for a SPECIFIC SET of companies in one call' with companyIds up to 50. It explicitly distinguishes from bolagsanalys_get_data by scope, so an agent can select correctly without relying on 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 an explicit when-to-use rule ('Use this for a specific N-company subset') and names the alternative for all companies ('to fetch ALL companies instead omit companyId on bolagsanalys_get_data'). Also notes the 50 cap is rejected, preventing wasted calls.

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?

The description discloses the mutation nature (removes token from memory and disk cache) and the impact on subsequent calls (no X-Api-Session header). This goes beyond the annotations (readOnlyHint=false already indicates a write), providing concrete behavioral context about side effects and state change.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the primary action, the consequence, and the explicit use case. The most important information is front-loaded, with no redundant or vague wording.

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 tool with no parameters and no output schema, the description covers the action, side effects, and usage context. An agent has everything needed to invoke it correctly, including when to call it and what happens afterward.

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 has zero parameters, and the schema is empty (coverage 100%). Per calibration, a baseline of 4 is given for 0 params. The description does not add parameter-specific semantics, but none are needed since there are no parameters to document.

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: 'Forget the locally-cached session token' and clarifies the effect (removes from memory and disk cache). It explicitly positions itself as the counterpart to set_session by describing the absence of the X-Api-Session header afterward, making its purpose distinct among siblings.

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

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

It gives a direct usage instruction: 'Use it to sign out of the current session.' It also explains the consequence (calls send no header until set_session again), which implicitly routes the agent to the appropriate sibling (set_session) for re-authentication. This is explicit enough for an agent to decide when to invoke it.

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

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

The description reinforces the readOnlyHint with 'Read-only' and 'Shared reference data; never writes', and gives a concrete sense of the operation's effect (a lookup returning parameter metadata). It does not mention pagination or performance, but the read-only reference nature is clear and consistent with annotations.

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 compact, front-loads the read-only nature and purpose, explains output fields, gives an example, and states the relationship to the downstream tool. It avoids unnecessary prose while preserving the key operational details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the readOnlyHint/openWorldHint annotationshola and a 100%-documented schema, the description covers the tool's role, how its results are consumed, and the meaning of `dataType`. No important missing context stands out for an agent selecting or invoking this tool.

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

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

The input schema already covers all parameters with descriptions and examples, and the description adds usage context by naming `nameContains`-style substring matching. However, it does not map each query parameter to the discovery workflow beyond the overall example, so value added over the structured schema is modest.

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 action ('Discover') with a clear resource ('real-estate benchmark parameter') and lists the returned fields (`code`, English name, `dataType`, enumValues). It also distinguishes this tool from the downstream consumer `fastighetsbenchmark_get_comp_timeseries` by explaining how the output is used.

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 clearly says to use it to resolve the `parameterCode` passed to `fastighetsbenchmark_get_comp_timeseries` and to read `dataType` to decide which CompDatum member to trust. It does not explicitly contrast with sibling lookup/search tools, but it gives strong contextual guidance for the main workflow.

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 and openWorldHint=true, so the safety profile is covered; the description adds genuine behavioral context (rows are self-describing via dataType, enum resolves to {value,name,enumType}, count:false enables cheap bulk paging). It only partially covers return/paging mechanics, but output schema carries that burden.

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 scope and the flow position, and every sentence carries signal. Slight redundancy in repeating 'read-only — never writes' at both the start and end keeps it from a 5.

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 an output schema exists, return values need not be re-explained; the description covers inputs, sourcing, ordering in the flow, and the dataType self-description pattern. Nothing essential for correct invocation 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 baseline is 3, but the description adds real meaning: comma-separated multi-value sedisIdIn, the source of parameterCode, the ISO date range semantics, and a concrete worked example. It goes beyond restating the schema.

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

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

States a specific verb and resource ('Pull the actual benchmarking numbers (CompDatum time-series) for one or more Comps'), scoping it to Comps and distinguishing it from the search/list siblings. An agent can immediately tell what this returns versus the discovery 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?

Explicitly positions this as 'the FINAL step of the §8 A6 flow' and names the three upstream tools that supply sedisId plus find_parameter for parameterCode. It gives the exact when-to-use and the dependency chain, leaving no routing 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, and the description reinforces this with 'Read-only' and 'never writes'. It adds useful behavioral context beyond the annotations: the list is tenant-scoped to the caller's data, and `detail: true` opts into a tenant-filtered `containsPropertyUnits` lineage. There is no contradiction with the annotations.

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 information-dense and front-loaded with the key facts: read-only, ownership, and result content. It flows logically from purpose to workflow to detail behavior to example. The only mild issue is that 'read-only' is stated twice, once at the start and again at the end.

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 that the output schema exists and all optional parameters are fully documented in the input schema, the description only needs to supply context, and it does thoroughly: ownership, tenant scoping, default lean behavior, a concrete example, and exact next-step parameter mapping. Nothing needed to invoke or chain the tool 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 the schema already documents all five parameters and the baseline is 3. The description adds value with a concrete `nameContains` example ('Stockholm') and explains how the returned `sedisId` feeds the downstream parameter `belongsToJamforelseobjektSedisId`, which is not present in this tool's 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 opens with a specific verb and resource: 'List YOUR comparison zones', and clarifies that Jämförelseobjekt are 'your clones of a Sedis-owned aggregate' returning `sedisId`. It also positions the tool as the 'FIRST step of the §8 A6 flow' and names the downstream sibling, making it easy for an agent to distinguish from related list/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?

The description gives explicit usage context: use this as the first step of the A6 flow, find a zone by name, then pass its `sedisId` to `fastighetsbenchmark_search_property_units`. It does not explicitly name a 'when-not-to-use' alternative such as `fastighetsbenchmark_list_reference_zones`, but the ownership contrast ('YOUR' vs 'Sedis-owned') provides enough directional guidance.

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

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

Annotations already declare readOnlyHint=true, so the doubled 'Read-only / never writes' phrasing is largely redundant. However, the description adds genuinely non-annotated context: this is shared reference data, identical for every key (i.e. no per-key or permission scoping), and it gives a concrete lookup example ('Stockholm' → id 21).

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 purpose and the sibling linkage, and takes only a few sentences. Slight waste in stating read-only twice ('Read-only.' and 'never writes'), which duplicates the annotation and buys nothing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and the description correctly focuses on purpose, shared-reference semantics, and id resolution. Nothing essential for correct invocation is missing, though a note on how paging interacts with filtering would round it out.

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 six parameters are already documented with examples. The description reinforces the meaning of `code` (official municipality code, SCB kommunkod) and illustrates nameContains, but adds no syntax or behavioral detail the schema lacks. 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+resource ('Look up municipality ids') and ties it directly to the consuming parameter (`municipalityId` filter of `fastighetsbenchmark_search_property_units`), making it trivially distinguishable from the other list_* siblings. An agent knows exactly what it returns (id, name, countryCode, code).

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 ties usage to resolving ids for the `municipalityId` filter of a named sibling tool, which is strong when-to-use guidance. It does not state exclusions or say when the other reference-list siblings would be preferred, but the context is clear rather than implied.

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 and openWorldHint=true, and the description repeats 'Read-only' twice, adding no credit. It does contribute genuinely new context — that this is shared reference data identical across keys and that names are Swedish — which goes beyond the annotations.

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 body is front-loaded and short, but 'Read-only' is stated twice (opening and closing) with no added information, which is wasted space against an annotation that already conveys it.

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?

An output schema exists, so return values need not be explained. The description is complete enough for a read-only reference lookup, covering the cross-tool usage rationale, though it omits any note on pagination scale for a list endpoint.

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 four parameters (page, sort, pageSize, nameContains) are already documented, including the 'Kontor' example. The description adds no syntax or constraint detail beyond the schema, 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+resource ('look up property-type ids') and immediately frames it relative to a sibling ('the propertyType filter of fastighetsbenchmark_search_property_units'), so the agent can distinguish it from the other list_* reference 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?

Explains the operational context: this is the lookup you perform before using propertyType in search_property_units or the EB0 parameter, with a concrete example filter ('Kontor'). It does not name when *not* to use it or compare against fastighetsbenchmark_find_parameter, so it falls short of 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, so the 'Read-only' and 'never writes' statements reinforce rather than add new safety information. However, the description adds valuable behavioral context beyond annotations: it clarifies that data is 'shared for every key' and has 'NO tenant filter', which is a non-obvious trait not captured by the readOnlyHint/openWorldHint annotations. This extra context justifies a score above baseline.

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 tightly written with no fluff. The most critical information (read-only, shared, no tenant filter) is front-loaded in the first sentence. Each subsequent sentence adds distinct value: output fields, use case, and an example. No unnecessary repetition 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?

The tool is simple (list with optional filters) and the output schema exists, so return values are already documented. The description covers the tool's purpose, data scope, example usage, and output field semantics. Pagination is handled by the schema (page/pageSize). Nothing an agent needs to correctly invoke this tool 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 input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds a concrete usage example ('Example: nameContains 'Stockholm'') which clarifies how to apply the nameContains parameter, and it mentions the output fields (sedisId, name, sourceName), providing helpful context for what the parameters filter. This example-driven guidance adds value beyond the schema, raising the score to 4.

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 a specific verb ('List'), a specific resource ('SHARED Sedis-owned reference zones'), and explicitly distinguishes these from private data by noting 'NO tenant filter (these are not your private data)'. This makes the tool's purpose unambiguous and differentiates it from sibling tools that likely operate on tenant-specific data.

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 provides clear context for when to use this tool: 'Use a reference zone as a market benchmark to compare against your own comparison zones and property units.' It implies the tool is for shared reference data, not private data, but does not explicitly name alternative tools or state when NOT to use it. The distinction from private data is implicit but sufficient.

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 and openWorldHint=true, and the description reinforces the read-only nature ('Read-only', 'never writes'). It adds useful behavioral context beyond the annotations: the response shape (each row exposes `containingCompSedisIds` as an array of ids, not nested objects), the reference-then-resolve pattern, and the note that creating/replacing/deleting a Samling is not exposed here. It doesn't describe pagination behavior, but the schema already documents page/pageSize defaults.

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 well-structured: it front-loads the read-only nature and the core purpose, then explains the response shape and the recommended workflow, and ends with an example. Every sentence earns its place, though the workflow explanation is slightly long 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 read-only list tool with a rich output schema, 100% parameter coverage, and annotations declaring read-only and open-world hints, the description is complete. It tells the agent what the tool returns, how to use the returned ids, and what the tool does not do. Nothing an agent needs to call 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 the schema already documents all four parameters. The description adds a concrete example for `nameContains` ('Stockholm offices') and explains the purpose of the returned ids, but it doesn't add meaning to the parameters beyond what the schema provides. 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?

The description states a specific verb ('List'), a resource ('your collections (Samling)'), and a key differentiator: it lists the tenant's own collections, not reference zones or comparison objects. It also names the sibling tool to use for resolving the returned ids, which distinguishes it from the other list tools in the sibling set.

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 says when to use this tool (to list your own collections) and gives a concrete workflow: take the `containingCompSedisIds` from each row and pass them to `fastighetsbenchmark_get_comp_timeseries` via `sedisIdIn` only for the collections you need. It also gives a concrete example (`nameContains 'Stockholm offices'`), which is actionable guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description usefully reinforces it ('never writes') and adds real behavioral context the annotations do not carry: tenant scoping to 'your data', a lean-by-default response with geometry opt-in, and the important constraint that an official fastighetsbeteckning is not a name and is not searchable. It does not cover pagination limits or ordering guarantees, but those live in 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?

Front-loaded with the highest-value facts (read-only, what it finds, the sedisId key) and then the flow context; every sentence carries routing or semantic information. It is a dense single paragraph rather than a skimmable list, and 'Read-only' / 'read-only — never writes' is mildly redundant.

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 an 11-parameter, zero-required search tool with an output schema present, the description covers purpose, id-resolution dependencies, downstream handoff, scoping, and the geometry-lean default — everything needed to invoke it correctly without explaining return values. Minor omissions (pagination defaults, sort behavior) are already documented in the 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 baseline is 3, but the description adds conceptual semantics beyond the field docs: sedisId is described as the stable, case-sensitive key to use in every later call, name is the customer's own designation (not the official designation), and belongsToJamforelseobjektSedisId is framed as the zone-to-units bridge. The worked example (propertyType 2, 'JO-A') further anchors usage.

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/search) and resource (YOUR property units / Fastighet) plus the exact match modes accepted: exact name, name fragment, property-type id, municipality, comparison-zone membership. It also explicitly distinguishes itself from siblings by naming the id-lookup tools and the downstream consumer (get_comp_timeseries), so an agent can place it in the pipeline without opening any schema.

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

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

Gives explicit when-to-use routing: it is 'the §8 A6 flow's object-finding step', take a comparison zone from list_jamforelseobjekt, filter here with belongsToJamforelseobjektSedisId, then pass the resulting sedisIds to get_comp_timeseries via sedisIdIn. It also names the alternatives for id resolution (list_property_types, list_municipalities), leaving nothing 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?

The description discloses meaningful behavior beyond the annotations: the token is cached in an owner-only file, sent on subsequent calls, never logged or echoed, and using this avoids a full restart. The annotations only indicate it is not read-only, so this extra transparency is valuable.

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 compact and front-loaded: the main action and trigger appear first, followed by the workflow and persistence behavior. No sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description covers the trigger, the input source, the action, the persistence behavior, and the security context. An agent has everything needed to invoke it correctly.

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

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

The schema already describes the token parameter in detail, including its origin and format, so the description adds little new information about the parameter itself. It reinforces the context but does not substantially expand on 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 uses a specific verb ('set') and resource ('sedis session token'), and clearly distinguishes this from a full client restart. The title reinforces the purpose, and the trigger condition makes the intent unmistakable.

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

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

It explicitly states when to use the tool ('when a tool returns Session re-verification required') and gives a clear step-by-step workflow. It does not explicitly name alternatives or exclusions, but the trigger-based guidance is strong enough for an agent to route correctly.

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