append_to_shared_doc

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly discloses the non-idempotent behavior ('a retry appends twice'), which is critical mutation-behavior information. It does not mention authentication/permission requirements or the return format, but the idempotency disclosure is the most operationally important trait for an append operation.

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?

Three sentences, front-loaded with the core action in sentence one and the critical non-idempotency warning in sentence two. Zero waste, all sentences earn their place. Could be slightly more structured, but it's tight and well-paced.

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 mutation tool with no annotations and no output schema, the description should add more: the 'content' semantics, what 'updated_user' means, and whether there's a size limit on appends. The non-idempotency and doc-id-or-url notes are valuable, but the parameter semantics gap and lack of return-value expectations leave it incomplete for a 3-parameter tool.

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 description coverage is 0% (no descriptions on any of the 3 parameters). The description mentions doc_id_or_url (accepts a doc id or URL) and implies content, but it never documents what 'content' represents (plain text? markdown? formatting restrictions?) or what 'updated_user' means semantically. With 0% schema coverage and 3 parameters, the description only partially compensates.

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+resource+action: 'Append content to an existing shared doc.' It clearly distinguishes this from create_shared_doc (create new) and extend_shared_doc (extend). It could more explicitly contrast with extend_shared_doc, which is its nearest sibling, but the append-vs-create distinction is clear.

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?

Provides clear usage context: it operates on existing docs, accepts a doc id or URL, and explicitly warns the agent to check with search_shared_docs before retrying due to non-idempotency. It doesn't say when NOT to use it vs extend_shared_doc (the nearest sibling), but the idempotency warning and pointer to search_shared_docs offer practical guidance.

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