app_set_active_document

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

With no annotations, the description carries the full burden and does not meet it. It says 'Returns: Dictionary with result of the operation,' which discloses nothing about failure modes (missing file, unopened document), whether the call is idempotent, or whether it changes visible UI focus.

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 core sentence is front-loaded and wastes no words. The Args/Returns block is generic boilerplate, and the Returns line adds little since an output schema already exists, but the overall length is appropriate.

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?

The output schema covers return values, so the vague Returns line is not a real gap. What remains missing for a lone-parameter state-changing tool is error and prerequisite behavior, and that is left unstated.

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%, so the schema offers only the title 'File Path.' The description does add meaning by specifying a full path to the document to activate, distinguishing it from a bare filename, but it gives no format example, extension expectations, or behavior for relative paths.

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 and resource: 'Set a specific document as the active (focused) document.' This clearly separates it from the read-oriented sibling app_get_active_document and app_list_documents. It stops short of naming siblings explicitly, so a 4 rather than 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?

There is no explicit when-to-use or when-not-to-use guidance and no alternatives named. The only hint is the phrase 'active (focused) document,' which leaves prerequisites such as whether the target document must already be open entirely to inference.

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