mark_filed

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

With no annotations, the description carries the full burden and does substantial work: it discloses that values are frozen, that locking is 'warning-only' (soft, not blocking), that PDF boxes are compared against the sheet, and that apply_pdf_values=true overwrites frozen values because the submitted return is the source of truth. It still leaves unstated whether a filing can be undone/unlocked and what the dry run actually reports.

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 mutation, then the PDF-comparison condition, then the operational directive 'Dry run first.' The second sentence is long and carries a stray line break, but every clause (locking target, overwrite precedence, dry run) adds 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?

For a 5-parameter mutation tool with no annotations and no output schema, the description covers the mutation semantics well but omits what the tool returns or reports under dry_run, whether the filing is reversible, and the accepted quarter format. Given the tool irreversibly alters declaration state, at least the reversibility question should be answered here.

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 0% and the description does explain dry_run, return_pdf and apply_pdf_values in prose, including the overwrite precedence rule. However, the required 'quarter' parameter is a free string with no enum and the description never specifies accepted format (e.g. 'Q1' vs '1'), and 'year' is only alluded to via 'the year folder' — real ambiguity an agent could trip on.

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 action (freeze declaration values, grey and lock the quarter's block column, expense rows and income rows) triggered by a specific event (the user submits a quarter). The verb+resource is concrete, but it never contrasts itself with the many sibling tools (vat_return, file_document, index_year), so an agent must infer that this is the post-submission locking 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?

Gives a clear precondition ('After the user submits a quarter') and a sequencing instruction ('Dry run first'), which is genuine usage guidance. It stops short of naming alternatives or stating when-not to use it (e.g. when the quarter isn't submitted yet, or when the return PDF is absent and apply_pdf_values would be meaningless).

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