appflowy_save_page

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

No annotations exist, so the description carries full burden. It discloses that markdown is converted unless plain_text is set, and warns about the parent_view_id hierarchy. However, it does not mention authentication needs, rate limits, or side effects like overwriting.

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 description is two concise sentences that front-load the purpose and critical details about content_format and parent_view_id. No unnecessary words.

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?

Given no output schema and nested parameters, the description covers core usage but lacks details on return values, error handling, and complete parameter semantics. It is adequate for a simple create tool but leaves some gaps.

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% (despite inline descriptions in the schema), so the description must compensate. It adds meaning for parent_view_id (hierarchy constraint) and content_format (default behavior), but does not explain other nested parameters like layout, view_id, or collab_id.

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 clearly states the tool's purpose: saving AI answers, notes, etc. as a new AppFlowy document page. It explicitly notes it's the default tool and distinguishes from siblings like appflowy_create_page by detailing conversion behavior for markdown.

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?

The description gives implicit usage guidance by explaining the content_format default and warning about parent_view_id not being the workspace_id, but it does not provide explicit when-to-use versus alternatives or mention when not to use this tool.

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