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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that it always returns 200 (with status 'none' when no delegation, never 404), the failure modes SCOPE_INSUFFICIENT and VALIDATION_FAILED, the no-sandbox-mirror constraint, and the zero-upstream-cost comparison with validate_action. No contradiction 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?

Front-loaded with the core purpose and return fields; every subsequent sentence adds distinct value: usage guidance, HTTP behavior, failure modes, sibling routing, environment constraint, and a docs link. No filler or redundant commentary.

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?

Compleet for a one-parameter, read-only tool with an output schema: covers return semantics, when to use alternatives, failure modes, environmental constraints (no sandbox mirror), and points to docs. The output schema can handle detailed return shapes, so the description doesn't need to reproduce them.

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

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

Schema description coverage is 100% for org_number (pattern, examples, MOD-11), so the schema already carries the parameter meaning. The description mostly repeats '9 digits, MOD-11' and adds a failure-mode note, but does not significantly enrich parameter semantics beyond the schema. 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 ('Return'), resource ('authorisation snapshot'), and scope ('calling consumer's delegation on a Norwegian organisation'), and enumerates the exact fields returned. It also distinguishes itself from sibling tools like list_acting_capacity, check_fullmakt, and get_company_authority.

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 explicit routing guidance: for a specific person's actions use list_acting_capacity, for preflight use validate_action, for per-agent-principal breakdown use check_fullmakt, and for statutory signing authority use get_company_authority. It also clarifies the tool's constraint of no per-action or per-actor input at v1, so an agent knows when not to choose it.

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

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

Annotations already mark this as read-only and idempotent. The description goes far beyond them by explaining that it reports the delegation state Apier RECORDED rather than a live Altinn PDP decision, that 'none' is a valid 200 response rather than a 404, that sandbox use yields SANDBOX_TOOL_UNAVAILABLE, and by enumerating failure modes. This is high-value behavioral context not available from annotations alone.

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?

Although the description is dense, every sentence earns its place: purpose, semantics, valid responses, failure modes, sandbox behavior, alternatives, and docs. It is front-loaded with the most important usage constraint ('BEFORE acting on its behalf') and remains tightly structured without fluff.

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

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

Given the single parameter, the presence of an output schema, and the annotations, the description is exceptionally complete. It covers when to use the tool, how to interpret results, what the tool does not do, failure modes, limitations, and sibling routing. 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%, and the single parameter org_number is already fully documented with pattern, examples, and a clear description. The tool description only restates 'Input: { org_number } (plain 9 digits)', adding no substantial new meaning over the schema. 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 opens with a specific verb and resource: 'Check your fullmakt state for a Norwegian company BEFORE acting on its behalf' and identifies itself as 'the read leg of the Fullmakt Rails.' This clearly distinguishes it from sibling tools such as request_fullmakt, revoke_fullmakt, and check_authorization.

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 when-to-use guidance ('BEFORE acting on its behalf'), names the exact alternatives for other operations (request_fullmakt, revoke_fullmakt), and distinguishes itself from the consumer-level check_authorization. It also documents failure modes and sandbox behavior, leaving little ambiguity about when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds valuable behavioral detail beyond those: failure modes (VALIDATION_FAILED for unknown codes, SCOPE_INSUFFICIENT for missing read:rulebook), the handover block semantics for human-resolvable errors, and fallback behavior to 'ukjent <noun>' for missing context values. No contradiction 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 dense and long, but every sentence earns its place: purpose, output envelope, failure modes, alternative tool, sandbox auth, and docs link. It is appropriately sized for a tool with six parameters and an output schema, though the single-paragraph format makes it slightly harder to scan than a more structured layout would.

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

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

For a tool with six parameters, an output schema, and annotations, the description is complete: it covers input semantics, interpolation behavior, failure modes, permission requirements, sandbox testing, and the sibling alternative. 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 baseline is 3. The description adds meaning beyond the schema by explaining that the optional context_* parameters carry placeholder values interpolated into the bokmål text and that missing values fall back to 'ukjent <noun>'. It also clarifies that error_code comes from a closed catalogue and links to the full list.

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: 'Resolve a structured Apier compliance error code into a Norwegian-bokmål Explanation envelope'. It clearly lists the envelope contents and explicitly distinguishes itself from get_company_obligations, so an agent can tell this tool apart from siblings 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 says exactly when to use this tool ('pass whatever code an Apier endpoint returned in an error envelope') and when not to: 'For a company's live obligations rather than an error explanation, use get_company_obligations instead.' It also gives sandbox testing guidance for the no-API-key case, which is a clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail: deterministic static map, no government system contacted, Europe/Oslo timezone for deprecation status, the `verified` flag with a warning to gate production actions, and specific failure modes including sandbox behavior. This far exceeds annotation coverage.

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

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

The description is a single dense paragraph but every sentence carries actionable information: purpose, usage, return flags, determinism, failure modes, scope, and docs. It is front-loaded with the primary purpose. While a touch long, 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 single-optional-parameter tool with an output schema, annotations, and sibling context, the description is impressively complete. It covers return semantics (verified flag, deprecation fields), failure modes, authentication scope, sandbox limitations, and a docs link. The output schema handles return-value details, so the description need not repeat them.

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 documents the parameter's pattern, length, and example. The description adds the key semantic of omission: 'omit it for the entire migration map,' which is not in the schema. It also reinforces the parameter's purpose, providing real value beyond the structured field.

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+resource statement: 'Discover the Altinn 3 equivalent of an Altinn 2 service or role code.' This clearly distinguishes the tool from all sibling tools, which focus on companies, deadlines, or authorization. The mention of the deprecation deadline further clarifies the tool's niche purpose.

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 states the context: 'serves remediation for any integration still on Altinn 2.' It explains both invocation modes (pass a code for a single mapping, omit for the entire map). It stops short of explicit exclusions or naming alternative tools, but the tool is unique among siblings.

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

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

Annotations cover readOnly/openWorld/idempotent, but description adds meaningful specifics: tri-state null semantics, currency always surfaced, 200-with-null for unknown org, failure modes, and cost behavior. This goes well beyond the structured data.

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 long but densely informative, covering purpose, limitations, alternatives, sandbox, cost, and docs. It is front-loaded with the main purpose and every sentence earns its place, though slightly verbose overall.

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

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

Despite an output schema existing, the description still covers usage context, edge cases, failure modes, cost, and sandbox fallback. It is fully complete for an agent to decide when and how to invoke the 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?

Parameter schema has 100% coverage with description, pattern, and MOD-11 validation note. The description repeats 'org_number (9 digits, MOD-11)' but adds no new meaning beyond the schema, 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?

Description opens with a specific verb+resource: 'Current-snapshot read of a Norwegian company's annual accounts' and explicitly distinguishes from siblings by pointing to get_company_verification for filing status and get_company_context for registry identity.

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 explicit when-to-use and alternatives: 'For the filing status as one input to a go/no-go verdict, use get_company_verification; for the registry identity, use get_company_context.' Also notes 'Current-snapshot only — no multi-year history' and failure modes that define prerequisites.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive behavior. The description adds deterministic classification, degraded-answer flagging, verification stamp semantics, absence-never-collapsed-to-no, failure modes, and cost/credit behavior, without contradicting 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?

Front-loaded with the core question and output classification, then organized into valuable sections: caveats, alternatives, failure modes, sandbox access, pricing, and docs. Dense rather than wasteful, though long enough that a perfect 5 is not warranted.

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?

Complete for a read-only resolver: output schema covers return structure, and the description supplies selection context, failure modes, authentication requirements, synthetic-fixture guidance, cost, and documentation link. 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?

Schema coverage is 100%: the input schema already documents the 9-digit pattern, an example, and MOD-11 validation behavior. The description only repeats the basic org-number requirement and adds no meaningful parameter detail beyond the schema.

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

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

States a specific verb-resource pair: resolves statutory signing authority for a Norwegian company from an org number. Lists the exact classification values and distinguishes itself from get_company_verification, list_acting_capacity, and check_authorization.

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 scopes when to use the tool: before acting on behalf of a company, with no actor input or Altinn delegations. Names concrete alternatives and their selection conditions, and even covers sandbox usage when no API key is available.

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 mark readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond them: the 24 h cache window, the full failure-mode list (NOT_FOUND, SCOPE_INSUFFICIENT needing read:brreg, UPSTREAM_TIMEOUT, VALIDATION_FAILED), the per-call cost and INSUFFICIENT_CREDITS behavior, the sandbox testing path, and the privacy guarantee ('never personal identifiers'). This is far more than the annotations alone provide.

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 long but dense — every sentence carries distinct operational information: purpose, fields, cache, selection rule, pairing, failure modes, alternatives, sandbox credentials, cost, and docs URL. It is front-loaded with the core purpose and flows logically. For a paid tool with many siblings and testing quirks, none of this 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 single-parameter, fully-schema-documented, output-schema-having read-only tool, this is complete. The description covers when to use it, when not to, failure modes, auth scope, caching, cost/credi t behavior, and the sandbox route — nothing an agent needs to cal it correctly is missing. The output schema relieves the description of explaining return values, and the schema covers the parameter.

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%: the schema already documents the 9-digit pattern, MOD-11 validation, and VALIDATION_FAILED behavior. The description adds value beyond this by identifying the parameter as the Brønnøysund registry identifier for Norwegian organisations and, more operationally, pointing to GET /api/v1/sandbox/fixtures as the source of valid test org numbers. It doesn't fully compensate beyond the schema, but the sandbox sourcing tip is a genuine increment.

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?

Opens with a specific verb+resource+scope: 'Retrieve the structured Brønnøysund identity slice for a Norwegian organisation by its 9-digit organisasjonsnummer', then enumerates the exact returned fields (legal name, organisasjonsform, NACE codes, addresses, dates, signaturrett/prokura codes). It explicitly names the siblings it is not — get_company_summary and get_company_profile — removing all ambiguity against the 24-tool sibling list.

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 selection rule: 'Choose this for the identity slice ONLY, without the compliance verdict', tells the agent what to pair it with ('pair with get_company_obligations or get_company_deadlines for the regulatory layer'), and names the precise alternatives for other needs ('for a compliance verdict, use get_company_summary instead; for the plain registry profile with NACE descriptions, use get_company_profile instead'). Nothing is left to inference.

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

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

Annotations already declare a safe read-only, idempotent profile; the description adds far more: DST-aware ISO 8601 due dates in Europe/Oslo, recurrence/adjustment flags, explicit failure modes (NOT_FOUND, SCOPE_INSUFFICIENT requiring read:brreg, VALIDATION_FAILED), sandbox authentication via Bearer apier_sandbox_test_<suffix> with synthetic fixtures, and costing (50 øre prepaid, INSUFFICIENT_CREDITS with top_up_url). This materially exceeds what the annotations 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 ~200-word description front-loads the highest-signal information (purpose, output contract, when-to-use, sibling routing) and defers operational details (sandbox, cost, docs) to the end. It has minor redundancy with the schema — the inputs summary and MOD-11 mention repeat schema text — but nearly every other clause carries non-redundant information.

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

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

Despite an output schema already existing, the description still sketches the entry shape and then covers scope requirements, all failure modes, auth setup, sandbox fixtures, credit shortfall behavior, pricing lookup, and a documentation URL. The ambiguity risk among siblings (get_company_obligations, get_public_deadlines, get_company_filing_history) is explicitly resolved for the first two. Nothing material for calling 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 coverage is 100% with detailed per-parameter descriptions — org_number's MOD-11 up-front check and horizon_months's default of 12 are already in the schema. The description's 'Inputs: {...}' summary and its framing of VALIDATION_FAILED as a correctable input error add marginal value beyond the schema, so the baseline of 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 ('Compute') and resource ('Norwegian regulatory filing calendar for a specific organisation') plus the output contract — one entry per (obligation, period) pair with obligation_id, due_date, legal_reference, and recurrence flags. It explicitly names sibling alternatives (get_company_obligations, get_public_deadlines) it is not, so an agent can distinguish it from its closest relatives.

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: 'Choose this for the calendar view — when does the next MVA / A-melding / Årsregnskap filing land?' It then states exclusions with named alternatives: get_company_obligations for the per-obligation compliance verdict, and get_public_deadlines for the entity-type-level calendar needing no org number and no API key. Nothing is left to inference.

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

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

Beyond the readOnlyHint/idempotentHint annotations, it discloses pagination mechanics (cursor vs legacy offset, deprecation), the empty-200-never-404 contract, mock gating, specific error codes, cost and prepaid billing, and sandbox fixtures. No contradiction 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 text is long but dense: every clause carries a distinct fact (purpose, pagination, mock gating, failure modes, cost, sandbox, alternative, docs). It front-loads the purpose and routes to the sibling at the end. No wasted words.

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

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

For a read-only audit-reconciliation tool with 4 params and an output schema, the description covers prerequisites, error handling, pagination, pricing, and sandbox testing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, but the description still enriches org_number with the MOD-11 pre-check and 'don't retry' guidance, explains the cursor's continuation semantics, and flags the offset deprecation — all 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?

The description opens with a precise verb ('Reconcile') and a concrete resource (Altinn filing history against Apier audit trail), and immediately distinguishes it from the deadline tool. It states exactly what the tool returns and how it pairs filings with audit records.

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 names the alternative tool for deadlines ('get_company_deadlines'), specifies the precondition (Maskinporten scope for live mode, sandbox fallback), and documents failure modes and cost, telling the agent exactly when and how to use it.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable transparency: deterministic evaluation, current-instant semantics with no as_of in v1, byte-for-byte bokmål descriptions, sandbox behavior, prepaid cost, and credit shortfall behavior. It does not contradict any 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?

The description is dense but well organized: purpose and return shape first, then usage routing, failure modes, sandbox access, cost, and documentation. Each sentence contributes actionable information, and there is no filler or tautology.

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 single-parameter read-only tool, the description covers return structure, failure modes, authentication scope, sandbox testing, pricing, credit shortfall, alternatives, and documentation. With an output schema also present, an agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100% and the org_number property description already covers the 9-digit pattern, example, MOD-11 validation, and VALIDATION_FAILED behavior. The tool description adds only supporting context such as sandbox fixture endpoints and the required scope, so the baseline of 3 is appropriate here.

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

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

The opening sentence states a specific action and resource: evaluate the Apier Rulebook for a Norwegian organisation and return every applicable obligation with state and legal reference. It also names what the tool is not — get_company_deadlines and get_public_obligations — so an agent can distinguish it from siblings immediately.

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 routes the agent: choose this for the full obligation menu, use get_company_deadlines for the calendar alone, and use get_public_obligations for entity-type-level obligations that need no organisasjonsnummer or key. It also names failure modes and the required scope (read:brreg), making the selection criteria concrete.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds meaningful behavioral context beyond that: the backing route is POST /api/v1/brreg/company-profile (counterintuitive for a read-only list tool), the MVA flag, the deduplication of person role CODES and never returning personal identifiers, and failure modes (NOT_FOUND, SCOPE_INSUFFICIENT, VALIDATION_FAILED). It also discloses that MOD-11 is enforced by the route and returns ORG_NUMBER_INVALID_CHECKSUM. A slight deduction because it doesn't describe pagination or detailed response shape, but the output schema exists to cover that.

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 every sentence earns its place: the resolution behavior, the field list, the route difference, sibling routing, the sandbox note, failure modes, and cost are all useful. It is somewhat long and the garbled trailing text ('Call: 50 øre... Docs: https...') is noise that likely came from a corrupted prompt, which prevents a 5. The key behavioral and routing information is front-loaded, so an agent gets the gist in the first two sentences.

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

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

Given the single required parameter, an existing output schema, and rich annotations, this description is largely complete. It even covers failure modes, cost, and a non-obvious route detail. It doesn't explicitly describe response pagination or the exact JSON shape, but the output schema presumably covers that, and the description already includes the most decision-relevant facts.

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 parameter description is unusually rich: it explains the pattern, gives an example, explicitly contrasts this tool with other get_company_* tools by stating it does NOT run MOD-11 client-side, and tells the agent what to do on ORG_NUMBER_INVALID_CHECKSUM (correct the number rather than retrying). This goes well beyond the schema's basic pattern and gives actionable guidance for the single required parameter.

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 ('Resolve') plus a precise resource ('organisasjonsnummer into a structured company profile from Brønnøysund Enhetsregisteret') and enumerates the returned fields. It also differentiates this tool from get_company_summary and get_company_context by naming them and their alternate purposes, so an agent can distinguish among the get_company_* 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?

The description explicitly states when to use get_company_profile versus get_company_summary ('evaluated compliance verdict') and get_company_context ('signaturrett/prokura role-code summary, distress flags, annual-accounts filing status'). It also flags the non-GET REST route and the absence of a sandbox mirror, which is practical routing guidance. The failure modes also help the agent decide whether this tool will work in a given context.

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?

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, the description adds valuable behavioral context: it composes multiple data categories in one round-trip from one rule version, obligations[] is byte-identical to get_company_obligations, deadlines[] matches get_company_deadlines, and failure modes are enumerated (NOT_FOUND, SCOPE_INSUFFICIENT, UPSTREAM_TIMEOUT, VALIDATION_FAILED). It also discloses sandbox authentication behavior and per-call cost, which are not available in structured fields. No contradiction with annotations exists.

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 every sentence earns its place: core purpose, usage routing, output composition, sibling relationships, failure modes, and sandbox/pricing/docs details. It is longer than minimal, but the tool is complex and the detail is high-value. The most important information is front-loaded in the first two sentences.

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 single-parameter tool with an output schema and read-only/idempotent annotations, this description is complete. It covers purpose, when to use it, what it returns, how it relates to siblings, failure modes, auth/sandbox behavior, cost, and documentation. The agent has everything needed to call it correctly and interpret the result. No significant gap remains.

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 has a rich description with pattern, example, and MOD-11 validation semantics. The description adds only that the param is a Norwegian organisasjonsnummer and that it is the sole exposed field, which is useful context but not substantial additional parameter meaning. The baseline of 3 applies because the schema carries the parameter documentation burden.

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: 'Retrieve a one-shot compliance summary for a Norwegian organisation by its 9-digit organisasjonsnummer.' It immediately distinguishes itself from siblings by stating it is the 'FIRST call when orienting against a company' and explicitly compares its output to get_company_obligations and get_company_deadlines. An agent can clearly tell what this tool does and how it differs from related 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?

Usage guidance is explicit and actionable: it names the tool as the first call, says to use get_company_deadlines when horizon control is needed, get_company_obligations for drill-down, and get_company_context for identity without a verdict. It also states what the tool does not expose ('Only { org_number } is exposed'). This gives clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes well beyond these by explaining the deterministic nature, the exact input keying (entity activity + visible signing authority), the semantics of pass/fail/unknown, that 'warn' is reserved, and that transparency signals never change the verdict. It also discloses failure modes, authentication scope, cost, and sandbox behavior, providing comprehensive behavioral context without contradicting 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 lengthy but well-organized: it starts with the core purpose and verdict logic, then moves to alternatives, failure modes, cost, and sandbox details. Every sentence contributes unique information; however, the overall length is high, and some operational details (like sandbox URLs and pricing) could be moved to dedicated fields if available.

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

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

Given the tool's complexity and the presence of an output schema and annotations, the description covers all essential aspects: purpose, input validation, verdict semantics, failure modes, required scope, cost, sandbox usage, and related tools. An agent has everything needed to call the tool correctly and handle errors, making it fully self-contained.

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

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

Schema coverage is 100% — the org_number parameter is fully described with a pattern, example, and detailed note about MOD-11 validation. The description only reiterates the 9-digit format and does not add additional meaning beyond the schema, so the baseline of 3 for high coverage 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 and resource ('get the deterministic verification verdict for a Norwegian organisation') and characterizes it as a fast go/no-go trust check. It distinguishes itself from related tools by explicitly naming get_company_authority for breakdown and other tools for context, summary, and obligations, 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?

Provides explicit usage context: 'before acting on a company's behalf' and lists precise alternatives — get_company_authority for breakdown, get_company_context for identity, get_company_summary for obligations, get_company_obligations for drill-down. It clearly indicates when this tool is appropriate versus when to use siblings, making routing decisions trivial.

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 annotations (readOnly, idempotent), the description adds valuable behavioral context: 'Free (unmetered), zero side effects', explicit failure modes (401, SCOPE_INSUFFICIENT, CREDIT_BALANCE_UNAVAILABLE, SANDBOX_TOOL_UNAVAILABLE), and semantic details like updated_at null meaning never topped up. It also clarifies why another key's balance cannot be read, enhancing transparency.

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

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

The description is front-loaded with the most important usage directive ('Call this BEFORE...'), followed by concise output and error details. Every sentence adds unique information, and the structure flows from usage to data to failure modes to alternative tools. No redundancy or filler.

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

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

Given zero parameters, a rich output schema, and thorough annotations, the description fully covers the tool's purpose, usage sequence, output semantics, pricing integration, and failure modes. It is complete enough for an agent to infer when and how to invoke this tool, including edge cases like sandbox behavior and 503 retries.

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

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

With zero parameters, the baseline is 4, but the description goes further by explaining the absence: 'no parameters, so reading another key's balance is structurally impossible.' It also details the return fields (api_key_id, balance_ore, currency, updated_at, top_up_url) and how to use them with get_pricing, adding semantic value beyond the empty schema.

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

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

The description clearly states the tool reads the authenticated key's prepaid credit balance, with the exact resource ('own prepaid credit balance') and explicit scoping ('ALWAYS the authenticated key's own'). It distinguishes from sibling get_pricing by noting 'NOT keyless — use get_pricing for keyless price discovery', making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Call this BEFORE a batch of metered calls to confirm the calling key's prepaid credit balance covers it, and AFTER a 402 INSUFFICIENT_CREDITS + human top-up to verify the funds landed.' It also names the alternative for keyless scenarios, satisfying the when-not/alternatives criterion.

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 the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses key behaviors: returns the rate with its valid date, weekday-only rates with prior business day fallback, client-side rejection for unsupported pairs, and a full list of failure modes. This significantly enriches operational understanding without contradicting 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 front-loaded with the core purpose, then efficiently presents usage constraints, failure modes, and an alternative tool reference. Each sentence carries operational value, and the length is justified by the domain complexity; no filler or redundancy.

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

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

The description is fully self-contained for a read-only lookup tool: it covers input semantics, edge cases (weekends/holidays), failure modes, authorization scope (read:norgesbank), sibling differentiation, and even summarizes return content (rate, date, source). Although an output schema exists, the description adds enough context to use the tool correctly without external references.

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

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

The input schema already provides full (100%) coverage with patterns and examples, but the description adds crucial semantic rules: the NOK-anchored requirement (exactly one side must be 'NOK'), the client-side rejection behavior (UNSUPPORTED_CURRENCY_PAIR), and the recommended approach for cross rates (fetch both NOK legs and derive). This depth of guidance goes beyond the schema and is highly actionable.

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 ('Fetch the most recent Norges Bank exchange-rate reference') with a clear resource (currency against NOK) and explicitly notes it takes no Norwegian-company input, distinguishing it from sibling tools. It also names an alternative tool for compliance-related needs, further clarifying its unique purpose.

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 states when to use the tool (as the canonical conversion benchmark for tax/accounting obligations) and when not to (for compliance obligations or filing deadlines, directing to get_company_summary). It also provides explicit usage constraints: exactly one side must be 'NOK', and cross rates should be derived manually, which guides correct invocation.

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 the annotations (read-only, idempotent, non-destructive), the description discloses key behavioral traits: it executes without an API key, the enforcement.live flag determines debiting, and the price list is derived from the same configuration as the 402 meter to prevent drift. It also lists failure modes, adding significant context not captured by 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 well-structured and front-loaded with the critical usage instruction. Every sentence adds specific value—keyless execution, return content, enforcement alignment, failure modes, and the alternative tool. It is dense but not verbose, and the flow from purpose to details is logical.

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

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

Given the tool's complexity and the existence of an output schema, the description is complete. It covers the return payload's key elements, failure modes, usage timing, and the relationship to get_credit_balance, leaving no ambiguity about when and how to invoke the tool. The docs URL also provides a fallback for deeper detail.

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 has zero parameters, and the description explicitly states 'Input: none — call with {}.' This reinforces the schema and leaves no ambiguity. With no parameters to document, the description fully satisfies this dimension.

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

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

The description clearly identifies the tool as a price list for Apier, with a specific imperative ('Call this BEFORE metered work') and explicit purpose: to check per-call cost and whether billing enforcement is live. It also distinguishes itself from the sibling get_credit_balance by clarifying its keyless, pricing-focused 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?

The description explicitly states when to use the tool ('before metered work'), provides a clear alternative for balance queries ('use get_credit_balance (Bearer key required) instead'), and notes failure modes. This gives the agent unambiguous guidance on selecting this tool.

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 the readOnly/idempotent annotations, the description discloses meaningful behavioral traits: deterministic output, DST-aware Europe/Oslo timezone, failure modes (SCOPE_INSUFFICIENT, VALIDATION_FAILED), and output structure (one entry per obligation/period pair, obligation_id, due_date, legal_reference, etc.). This adds substantial context beyond 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 detailed yet every sentence serves a purpose: purpose, output structure, usage guideline, determinism, input, failure modes, alternative tool, and docs link. It is well-structured and front-loaded with the core purpose.

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 are already covered. The description fills all remaining context: usage scenarios, failure modes, determinism, timezone specifics, and sibling tool differentiation. It is complete for a tool with one optional parameter.

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. The description adds extra value by explaining the year's default behavior ('defaults to the current Oslo year'), the valid range (2020–2100), and the failure mode VALIDATION_FAILED on year shape, which are not fully captured in the schema.

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

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

The description clearly states the tool computes the universal Norwegian regulatory filing calendar for covered categories (MVA, A-melding, Årsregnskap), independent of any specific organisation. It uses a specific verb (compute) and resource (universal filing calendar), and explicitly distinguishes from sibling get_company_deadlines.

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 explicit when-to-use guidance: 'Choose this tool for questions like when is the next MVA filing deadline that don't depend on a specific org_number — it requires no organisasjonsnummer.' Also names the alternative: 'For a specific company's filing calendar rather than the universal one, use get_company_deadlines 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 declare readOnly, idempotent, and non-destructive behavior, but the description goes further by disclosing failure modes (VALIDATION_FAILED, SCOPE_INSUFFICIENT requiring read:rulebook, UPSTREAM_TIMEOUT) and explaining the tier_2_required boolean semantics. This adds significant context beyond the structured 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 well-front-loaded and packs substantial information, but the alternative-tool guidance is slightly redundant ('layers on commercial data' vs. 'evaluated obligations' for the same alternative). Otherwise, 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?

With a single parameter, a rich output schema, annotations, explicit failure modes, and clear alternatives to sibling tools, the description fully equips an agent to understand the tool's purpose, limitations, and invocation. It also includes a documentation link for deeper reference.

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 covers entity_type with a closed enum and description, but the description reinforces the absence of an 'OTHER' fallback and ties the parameter to concrete use cases, such as retrieving baseline filings for an Enkeltpersonforetak. This adds value beyond the schema.

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

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

The description clearly states the tool retrieves the universal obligation set for a Norwegian entity type, specifying the exact scope (pre-company Tier-2 data) and answering concrete questions like 'what does an AS owe?'. It distinguishes itself from sibling tools like get_company_obligations, which handle per-company evaluated obligations.

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 states when to use this tool ('without naming a specific company') and points to get_company_obligations for per-company evaluation. It also advises that entity_type is a closed enum with no fallback, clarifying correct input usage.

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 the readOnly/idempotent/destructive annotations, the description adds substantive behavioral detail: inputs are HMAC-hashed, the raw value is never persisted/logged/returned, only `actor.fnr_hmac` is echoed, and failure modes SCOPE_INSUFFICIENT and VALIDATION_FAILED are listed. It also discloses the absent sandbox mirror and includes legal-reference metadata per returned action token, giving the agent a clear model of side effects and limitations.

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?

Although the description is long, every sentence earns its place: core purpose, internal role mapping, input handling, failure modes, sibling routing, sandbox limitation, and docs reference. The most important scoping information is front-loaded in the first sentence, and the rest is dense, non-redundant, and directly actionable.

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

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

The description is fully self-sufficient for a 2-parameter tool: it explains what the tool computes, what inputs to supply, how sensitive data is handled, which failures can occur, when to use siblings, and the sandbox limitation. Since an output schema exists, the description does not need to enumerate return fields, and the provided context is more than adequate for correct selection and invocation.

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 structured descriptions already document both parameters. The description still adds value by explaining the runtime handling of fnr (HMAC-hashed, never persisted, only hmac echoed) and clarifying the semantic roles of the two identifiers, which goes beyond the schema's basic type and pattern information.

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

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

The description names a specific verb ('Resolve'), a resource ('every Norwegian regulatory action a person is currently authorised to perform on behalf of a specific organisation'), and explicitly distinguishes itself from siblings like check_authorization and get_company_authority. An agent can tell exactly what this tool does and how it differs from related 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?

It explicitly states when to use alternatives: 'For your own consumer's delegation snapshot, use check_authorization instead; for the company-level statutory signing authority with no actor input, use get_company_authority.' It also instructs the agent to dry-run action tokens with validate_action, giving concrete guidance on how to safely use the output.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the burden is lowered, and the description exceeds it substantially. It discloses privacy behavior (personal-field rows withheld without entity_id, 'personal_fields_withheld: true'), HMAC-signed cursor rejection ('an edited one is rejected as CURSOR_INVALID'), three named failure modes (SCOPE_INSUFFICIENT requiring read:changes, VALIDATION_FAILED, CURSOR_INVALID), sandbox absence (SANDBOX_TOOL_UNAVAILABLE), and the observation_kind cache-warm-up/transition distinction. This is rich behavioral context beyond any structured field.

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 dense single paragraph where nearly every clause earns its place: purpose and sources first, then filters, privacy behavior, pagination mechanics, error modes, and a docs link. It is long (~200 words), but the complexity — 8 parameters, keyset pagination, signed cursors, failure modes — justifies the length. Minor structural improvement would be line breaks between the behavioral concerns, but the most important information 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 tool this complex — 8 parameters, keyset pagination, cursor signing, privacy filtering, auth scope, sandbox behavior — the description covers everything an agent needs to call it correctly: filter semantics, offset mechanics, the verbatim cursor rule, error codes and their meaning, required scope, and the sandbox limitation. The output schema covers return values, so nothing 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%, establishing a baseline of 3. The description adds genuine value beyond the schema: it groups the four filters ({ source, entity_type, entity_id, change_type }), frames from/to as a detected_at range, includes the route default for limit (1–500, default 50), and clarifies cursor semantics ('HMAC-signed; an edited one is rejected') beyond the schema's bare 'pass back verbatim' note.

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

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

The opening verb 'Read' names a specific resource ('Apier's cross-source change archive') and the precise content ('detected created / updated / deleted events across the upstreams Apier polls'). The stated purpose, 'so agents drive incremental sync instead of re-fetching whole entities,' tells an agent exactly what this tool is for and clearly distinguishes it from sibling read tools like search_companies or get_company_profile.

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 a clear use context ('drive incremental sync instead of re-fetching whole entities'), which implies when this tool is the right choice. However, it never names an alternative sibling or states an explicit exclusion — e.g., it doesn't say 'use get_company_profile when you need a current snapshot.' The guidance is present but implicit rather than explicit.

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 state readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes far beyond: it discloses single-use atomic consumption, exact-once delivery of the plaintext_key, uniform error behavior for expired/used/revoked/unknown tokens, and the MAX_KEYS_REACHED 409 case where the token is NOT consumed. It also notes the token is never logged, adding security-relevant context. This fully discloses behavioral traits, and no annotation contradiction exists.

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?

Although the description is relatively long, every sentence conveys critical operational detail. It is front-loaded with the core action, then covers keyless nature, single-use, failure modes, and next steps, each earning its place. There is no filler or redundant repetition of the schema; the text is dense with actionable information.

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

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

Given the tool's complexity (onboarding, single-use credential, failure modes) and the presence of an output schema, the description is complete: it specifies success payload and status, exactly-once storage imperative, all relevant failure modes with proper agent behavior, and a docs link. It also situates the tool within the broader workflow by naming subsequent tools. No gaps remain for the agent to safely invoke the 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?

Input schema already has 100% coverage with a detailed description of the token parameter, including single-use, not-logged, and example format. The description adds broader meaning by explaining the token IS the credential in keyless onboarding and that minting/revocation are dashboard-only, enriching the agent's understanding of the parameter's role. It also clarifies retry semantics with the same token on 409. This goes beyond the schema, hence a 4 rather than a 3.

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 clear, specific verb+resource: 'Convert an owner-issued key-issuance token into your own API key.' It explicitly positions this as the headless onboarding step, distinguishing it from all sibling tools in the context (none of which cover key redemption). This is unambiguous and uniquely identifies the tool's purpose.

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 explicit when and when-not: 'for an agent that holds no credential yet' and 'Minting and revocation are dashboard-only by design, so an agent can never self-issue authority.' It also names direct post-onboarding alternatives: 'use get_pricing (keyless) ... and get_credit_balance (with your new key).' Even failure handling instructs when to retry vs. never retry, making use conditions crystal clear.

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

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

Annotations already declare idempotentHint=true, but the description adds crucial behavioral context: the delegation is unusable until approval, warnings[] on 201 require reconciliation not retry, retries are dedup-safe via deterministic Idempotency-Key, and system_user_id is bound write-once. It also enumerates failure modes. This richly extends the annotation profile 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 long but dense; every sentence serves a purpose. It front-loads the core purpose, then covers inputs, failure modes, warnings handling, idempotency, and sibling routing in a logical order. No filler or redundancy—given the tool's complexity, this length is warranted and well-structured.

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

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

The description is exceptionally complete: it specifies input constraints, required approvals, idempotency guarantees, warning semantics, failure modes, and precise alternative tools. It even notes the lack of a sandbox mirror and links to docs. Despite having an output schema, it explains the write-once binding and the pending→active transition, which schema alone wouldn't convey. Nothing an agent needs to call 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 parameters. The description adds value by summarizing the input set with semantic emphasis: 'agent_principal_id (uuid, YOUR OWN)' reinforces ownership, 'org_number (9 digits)' underlines format, and 'scopes (non-empty string[])' clarifies constraints. It also flags the SCOPE_INSUFFICIENT failure mode, tying parameters to runtime behavior. This exceeds the baseline 3.

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 defines the tool with a specific verb ('Broker a fullmakt') and a precise resource ('legally-grounded, scoped, revocable company→agent authority delegated through an Altinn systembruker'). It clearly distinguishes it from siblings by naming alternatives: 'use check_fullmakt instead' and 'use revoke_fullmakt instead', so an agent can tell them apart.

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 when-to-use context: it brokers, persists, and binds the delegation, requires approval via delegation_url, and notes the 'No sandbox mirror' limitation. It provides clear exclusions by naming alternatives for inspection (check_fullmakt) and withdrawal (revoke_fullmakt), and states the required read:altinn scope for invocation.

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 show destructiveHint=true, but the description adds critical behavioral detail: revocation flips the principal to terminal 'revoked' (irreversible), is idempotent (200 no-op on already-revoked), and warnings[] carries named tokens (principal_revoke_failed, etc.). It also notes the tool is local-authoritative and immediate. No contradiction 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 dense but well-structured, front-loading purpose and key constraints, then moving to behavior, idempotency, warnings, input, and failure modes. Every sentence adds value; no redundancy. Slightly long but justifiably so given the complexity.

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 destructive, irreversible mutation with warning tokens and failure modes, the description is remarkably complete. It covers when to use, behavior, idempotency, warning interpretation, input format, failure modes, and sandbox limitation, plus a docs link. The output schema is present, so return values are covered structurally. Nothing critical 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 covers both parameters with descriptions, but the description adds crucial semantics: agent_principal_id resolves server-side (so client cannot redirect), reason is audit-only, and empty reason is rejected. It also specifies failure modes tied to parameters (unknown id returns FULLMAKT_PRINCIPAL_NOT_FOUND). This significantly enriches understanding beyond the schema.

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

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

The description clearly states the tool's purpose: revoke a fullmakt (delegation) and retire the agent principal. It uses a specific verb ('revoke'), names the resource ('fullmakt'), and explicitly differentiates from siblings ('broker with request_fullmakt, inspect with check_fullmakt'), making its place in the API obvious.

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 explicit usage guidance: mentions this tool is for revocation, while request_fullmakt is for creating (broker) and check_fullmakt for inspection. It also explains constraints (only agent_principal_id needed, server-side resolution prevents redirecting) and the terminal consequence ('never resurrected; create a new principal to act again'), which tells the agent when to choose this tool and what to expect.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable complementary detail: it returns a token-efficient candidate list of up to ten matches with five fields each, lists specific failure modes including the required scope (read:brreg), and discloses that there is no sandbox mirror. No contradiction with annotations exists.

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

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

The description is front-loaded with the core purpose and first-step guidance, then moves through result shape, follow-up actions, error recovery, failure modes, and sandbox behavior. It is dense but every sentence earns its place, with no filler or repetition.

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

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

For a single-parameter, read-only search tool with an output schema, this description is complete. It covers when to call it, what results look like, what to do next, how to recover from NOT_FOUND, which failure modes to expect, and how sandbox behavior differs. 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?

Schema description coverage is 100%, and the schema's name parameter already documents length, trimming, free-text matching, legal-form omission, and NOT_FOUND broadening. The description mostly restates these constraints or gives usage advice rather than adding new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it resolves a Norwegian company name to its 9-digit organisasjonsnummer by searching Brønnøysund's public Enhetsregisteret. It also clearly distinguishes itself from sibling tools by explaining that every other company tool requires the org_number, making this the necessary first lookup step.

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 to use this as the FIRST call whenever you have a name but not an org_number. It names the follow-up tools (get_company_summary, get_company_context), tells the agent to skip deleted or bankrupt matches unless intended, and gives concrete NOT_FOUND handling: broaden the name and drop the legal form rather than retrying the same input.

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

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

Annotations already declare readOnly/idempotent/destructive false, but the description goes further: it enumerates concrete side-effect exclusions (no Maskinporten, no Altinn/Skatteetaten/NAV submission) and discloses behavioral traits beyond annotations: 'the validator never throws', the verdict's five prerequisite slots, the DRY_RUN_DISCLAIMER, and the failure modes. This is exactly the kind of behavioral context that makes an agent safe with the tool.

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

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

The description is long but information-dense and front-loads the most critical fact: zero upstream side effects. It earns most sentences. It loses a point for redundancy: 'No sandbox mirror' and 'under a sandbox bearer call submit_vat_return instead' convey the same instruction twice, which 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?

Even with an output schema present, the description explains the verdict shape, the disclaimer, preview echo, failure modes, required scope, and alternative submission path. It also includes a docs link. For a complex dry-run validator tool, this is thoroughly 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?

The schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds extra meaning by noting the inputs mirror the /v1/actions/execute body and explaining that the nested payload is intentional and mirrors the upstream government schema, which helps an agent construct correct payloads without flattening them.

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

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

The opening sentence states a specific verb and resource: 'Run the Apier dry-run validator against a proposed regulatory action.' It also explicitly contrasts itself with the live execute path and names submit_vat_return as the sibling for actual filing, so an agent can tell it apart without opening another 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?

It says 'Use this BEFORE the live execute path' and warns that under a sandbox bearer one should 'call submit_vat_return instead.' It also surfaces the required read:actions scope via SCOPE_INSUFFICIENT, giving clear when-to-use and when-not-to-use criteria.

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