Company filing calendar

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.