agent_submit_declaration_pdf

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

Annotations already cover the safety profile (write, non-idempotent, open-world, non-destructive). The description adds meaningful behavior beyond that: the local agent signs with the certificate, uploads to the portal, returns the ANAF upload index, and the recipisa lands in the SPV inbox and on StareD112. This gives the agent real workflow context that the annotations cannot express.

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 definition is dense but well front-loaded: the action, the artifact, the signing/upload mechanics, the return value, and the prerequisites all appear in order with no filler sentences. It is longer than average but each clause carries 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 write tool with no output schema, the description explains the lifecycle well: what is returned (upload index), how to track it (anaf_declaration_status with CUI/CNP), and where the recipisa appears. The main omission is that certificateId semantics are never touched, and error/auth failure modes are unmentioned.

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 50%: file and fileName are documented in the schema, but pin and certificateId are not. The description compensates partially by explaining the three PIN sources (pin argument, STORNO_AGENT_PIN, or the remembered PIN on this machine), which is genuinely useful. It says nothing extra about certificateId, so half the parameters still rely on bare 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 states a specific verb and resource: it files a DUK-generated declaration PDF at ANAF, signed locally with a certificate and uploaded to WAS6DUS. This clearly distinguishes it from generic siblings like declaration_pdf (a generator) or agent_sign_pdf (signing only). It does not explicitly contrast with declarations_submit or declarations_file_via_agent, so it falls short of a 5.

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?

Implicit usage is clear — you need a DUKIntegrator PDF and want it filed. It also names anaf_declaration_status as the follow-up tool for tracking, which is helpful. However, with close siblings such as declarations_submit and declarations_file_via_agent present, it never states when to use this one instead of those, leaving a real routing gap.

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