gitea_status

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

With no annotations, the description carries full behavioral burden. It discloses that secrets are NEVER returned, explains what gitAvailable false means, and clarifies what remains available. It stops short of stating whether the tool performs any network calls or strictly reads local config, but the behavior that matters for an agent is well covered.

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 dense but front-loaded with the core purpose, then systematically enumerates outputs and fallback semantics. Though it runs long as one sentence, every clause carries meaningful information and no filler. The 'Takes no input' note at the end is efficient.

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?

For a no-input diagnostic tool with no output schema, the description enumerates every returned field, explains the gitAvailable false path, states the no-secrets guarantee, and gives explicit trigger conditions. Nothing an agent needs to interpret or act on the result is missing.

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 tool has zero parameters and the schema is empty, so the baseline is 4. The description explicitly says 'Takes no input,' confirming there is nothing to supply. This fully covers parameter semantics.

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 verb 'Report' is specific and the resource is clearly the resolved connection and credential state. It enumerates the exact outputs (baseUrl, credential candidates, gitAvailable, session target), which fully distinguishes it from all sibling tools, none of which diagnose connection state.

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?

Explicitly states when to use it: 'when a tool returns 401/403 or NotConfiguredError.' It also provides actionable fallback guidance for when gitAvailable is false (install git or set GITEA_REPO_URL / GITEA_TOKEN), making the usage context and alternatives crystal clear.

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