fiscal_calendar

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

No annotations are provided, so the description carries full burden. It discloses that dueDate is moved to the next working day after weekends/holidays, explains status categories (due, overdue, filed) with their conditions, and notes that allCompanies returns items for every visible company. It doesn't mention side effects (assumed read-only) or error cases, but given the breadth of behavior covered, it is quite transparent.

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 packed with necessary details. Every sentence contributes: it covers defaults, item fields, dueDate logic, status semantics, appliesBecause values, declarationType linkage, allCompanies behavior, and rule basis. There is no fluff or repetition; the structure flows from purpose to specifics.

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 there is no output schema, the description fully defines the return items: code, label, dueDate, nominalDueDate, daysLeft, period, appliesBecause, declarationType, status. It also explains the filtering logic (unfiled last month) and the allCompanies scope. It ties declarationType to declarations_create for follow-up actions. Nothing essential for an agent to call and interpret results is missing.

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

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

Schema coverage is 100%, so the description already has parameter docs. However, it adds default values (days=60, from=today) that aren't fully in the schema, clarifies the meaning of allCompanies as the 'accountant view', and explains the interplay with company settings. This goes beyond the schema and helps disambiguate parameter usage.

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

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

The description clearly states the tool's purpose: it returns filing deadlines for a company over a specified window. It lists specific deadline types and details about each item, making it distinct from sibling tools like declarations_list or declarations_create. The verb is implicit (returns/gets), but the resource is explicit and the scope is well-defined.

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 explains the default parameters and the allCompanies option for an accountant view, which implies when to use each. It also mentions that declarationType is meant to be passed to declarations_create, linking usage to another tool. However, it doesn't explicitly contrast with alternatives or state 'use this when...' — that's left to inference.

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