app_help

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

Although there are no annotations, the description conveys the tool's behavior: it's a documentation retrieval tool that returns the TOC or specific pages. It explains the two-step invocation, fuzzy matching, and cross-reference handling. It doesn't explicitly state it makes no modifications, but the documentation nature implies a non-destructive read operation. This is adequate transparency, though it could be more explicit about return format or side-effect absence.

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 information-dense but every sentence adds value. It starts with a clear identification, then usage examples, followed by practical instruction. There is no fluff or repetition; the structure is logical and easy to parse, making it appropriately sized for a documentation/help tool.

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 the tool's simplicity (one optional parameter, no output schema), the description is remarkably complete. It covers purpose, use cases, invocation pattern, parameter semantics, and behavior. It also lists specific topics it can answer about (edit times, delete records, etc.), which helps the agent know when to delegate to this tool. The lack of an output schema is mitigated by the clear explanation of what the tool returns (TOC or pages).

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?

The schema already describes `topics` as slug strings with fuzzy matching and omission for TOC. The description adds significant extra semantics: the recommended two-step workflow (first no args for TOC, then with topics), how cross-references map to slugs, and the note about platform applicability in the TOC. This goes beyond the schema, enhancing the agent's understanding of how to use the parameter effectively.

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 provides official ATimeLogger documentation and is used to answer questions about how the app works or how to do things the other tools cannot. This distinguishes it from sibling action tools like start_activity or time_report, making its purpose specific and unambiguous.

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 explicitly tells when to use the tool (for app questions or tasks other tools can't do, with examples), and gives a clear calling pattern: call with no arguments for the table of contents, then with `topics` to fetch pages. It also instructs to answer from the docs, not memory, and explains cross-references, providing comprehensive usage guidance.

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