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

With destructiveHint/openWorldHint annotations already set, the description still adds real value: it discloses the docfarm landing behavior, the immediate-vs-pending outcomes for existing vs new users, that the result reports whether an invite email was sent, and the fork-vs-overwrite side effect that explains the destructive flag. It stops short of noting rate limits or exact permission requirements, so not quite a 5.

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?

Dense single paragraph, but front-loaded with the core action and outcome, then the required params, then the clarification instructions. A couple of clauses (the fork/auto-share detail) are repeated between description and schema, costing a little tightness without bloat.

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?

No output schema exists, yet the description covers the meaningful return signal (whether an invite email went out), the ownership/auth precondition, the account scoping sibling, and both doc-identification routes. Nothing needed to call this correctly 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 baseline is 3, but the description goes further by explaining the fork/auto-share-back semantics of allow_overwrite and noting that doc_name is fuzzy-matched and slug is an alternative identifier. That meaning is not expressed in the schema text itself.

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 verb (invite) and resource (collaborator on a doc) plus the constraint that the user must OWN the doc, which distinguishes it from sibling tools like update_doc_settings or duplicate_doc. An agent immediately knows this is the invite/share path, not a general edit.

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?

Explicit when-to-use and when-to-ask: 'If you don't have the email, ask for it' and 'if the user hasn't said whether the person should edit directly or only make a copy, ask before calling, don't guess.' It also surfaces the ownership precondition, so the agent can route elsewhere when the doc isn't owned.

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