Daily BORME digest

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

Goes well beyond the readOnly/idempotent annotations by disclosing the access model (one request per call; without an X-API-Key only the last 7 days, key URL provided) and the empty-day edge case (weekends/holidays return total_events 0). It also flags a real correctness trap: INSOLVENCY_STATUS can represent any stage, so the payload must be read before asserting a company was declared insolvent.

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

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

Front-loads purpose, then the alternative, then the return shape, then caveats — a sensible information hierarchy. It is on the long side and the parenthetical enumeration of excluded act types (SUSPENSION_OF_PAYMENTS, BANKRUPTCY_LEGACY, PROVISIONAL_SHEET_CLOSURE_INSOLVENCY) is verbose, though each clause carries real decision value.

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

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

There is no output schema, and the description compensates by spelling out the returned JSON shape (date, total_events, by_type, top_provinces, insolvencies[{company, province}]). Combined with the auth window, empty-day behavior, and the insolvency-interpretation warning, an agent has everything needed to call it and to interpret the result.

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 schema already documents the YYYY-MM-DD format and the omit-for-latest default, so the description needn't repeat it. What it adds is behavioral: a day without a gazette yields total_events 0, which helps interpret the parameter's edge cases but doesn't extend the format semantics.

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 and resource ("Summarise one BORME publication day") and immediately enumerates the exact contents: totals, counts by act type, top provinces, insolvency notices. It explicitly distinguishes itself from search_events, so an agent can route between the two without opening either schema.

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

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

Gives explicit when-to-use ("what was published today" or a day's figures) and names the alternative with the exact invocation pattern: to read the notices use search_events with date_from = date_to = that day. That is a concrete hand-off rule, not just a mention of a sibling.

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