get_document_status

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

With no annotations provided, the description carries the full behavioral burden and does so well: it explicitly states that the tool only reads, never saves or recomputes, and explains subtle dirty-flag behavior including the null case meaning the flag could not be read rather than assumed clean. It also discloses the App.save()/saveAs() caveat about the GUI modified flag.

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 front-loaded with the core read-only purpose and then explains parameter behavior and return-field semantics compactly. Every sentence earns its place, especially given the absence of an output schema and annotations.

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?

There are no annotations and no output schema, so the description must explain both behavior and return-field meaning. It does this thoroughly by defining modified, saved_once, needs_recompute, needs_save, file_path, and file_exists, including the important null semantics for needs_save.

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 description must compensate for the lone doc_name parameter. It does so by explaining that an empty string lists all documents and a named value inspects that document, which is the key semantic needed to invoke the tool correctly.

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 and resource: read document status for open documents, explicitly without saving or recomputing. It is clear enough to distinguish from mutation tools like create_document or reload_document, though it does not name a sibling alternative such as list_documents.

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 clearly explains the usage split: an empty doc_name lists all documents, while a non-empty value inspects one named document. It does not compare directly against sibling list or inspect tools, but the operational guidance for this tool is clear.

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