share_document

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

With no annotations, the description carries the weight and does well: it discloses that this is a network upload to a deployed server, that links expire and become unusable while images stay in the account, and that revoke breaks the link immediately with images reclaimed later. Required environment variables (DINGCARD_SERVER_URL plus account/token) are called out. Authentication details and error behavior are left vague.

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 output contract and QR behavior are front-loaded and the mode and expiry semantics follow in a sensible order. It is dense and sentence-long but nearly every clause carries information. Slight redundancy with the schema on expiresInHours and the document parameter shapes.

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 an 8-parameter, zero-required tool with no output schema, the description supplies the return shape ({ ok, share: { id, url, expiresAt, imageCount } } plus QR image) and the environment prerequisites, which is what an agent needs. It does not say what happens when no document source is supplied for the share action, a small gap.

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 baseline is 3, but the description adds real meaning beyond the schema: it explains that documentId, document, and documentPath are interchangeable routes to the same input and that the Markdown envelope matches render_markdown's document. expiresInHours bounds and default are repeated from the schema rather than extended, so it is not a 5.

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 names a concrete workflow with a specific verb chain: render the document as images, upload to the deployed DingCard server, and produce a login-free share link. It also scopes the accepted inputs (free-canvas documentId / v44 document vs. a Markdown card envelope) and distinguishes itself from render_markdown by referencing the same document shape. An agent can tell it apart from render_document at a glance.

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?

It explains the three action modes clearly: share is the default, list enumerates existing shares, and revoke tears down a share by id. It also gives the practical use case (creating on desktop, sending from phone) and notes expiry semantics. It never explicitly states when to prefer a sibling like render_document instead, which keeps it below 5.

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