Tool Documentation Contract

Use this contract for every Hana tool page so documentation authors can produce consistent, implementation-accurate tool docs.

Required sections

Every tool page must include these exact H2 headings:

1. ## What it does
2. ## When to use
3. ## Supported operations/arguments
4. ## Invocation examples
5. ## Troubleshooting
6. ## Permissions/limits

Section requirements

What it does

• Explain the tool in 1-3 short paragraphs.
• Clarify the business outcome the tool enables.

When to use

• State practical trigger conditions.
• Differentiate from adjacent tools when there is overlap.

Supported operations/arguments

• Prefer a table with operation name, invocation pattern, and arguments.
• Mark required vs optional arguments.
• Use argument names that match implementation terminology.

Invocation examples

• Provide at least 3 copy-paste-ready examples.
• Include at least 1 common case and 1 edge case.
• Keep examples in fenced text blocks.

Troubleshooting

• List the top failure modes users actually hit.
• Include corrective steps, not just symptoms.

Permissions/limits

• Document auth requirements, role constraints, and connector dependencies.
• Document notable limits (scope, data freshness, caption availability, etc.).

Formatting standards

• Use plain-language descriptions and concrete wording.
• Keep invocations explicit about scope and time window when relevant.
• Use exact command syntax for slash commands (for example, /privateChat ...).

Review checklist

• All six required sections exist with exact heading names.
• Invocation examples contains at least 3 examples.
• Supported operations/arguments includes required/optional clarity.
• Troubleshooting has actionable fixes.
• Permissions/limits reflects current product behavior.