configure_gitea

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

With no annotations provided, the description carries full disclosure burden, and it does so exceptionally well. It discloses session-scoping, non-persistence, credential re-discovery triggers, that tokens never pass through this tool (always read from local sources), the three credential sources, and username's strict narrowing behavior with no fallback. This is rich behavioral context for a configuration tool.

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 well-structured and every sentence earns its place. It front-loads the key insight (session-scoped, never persisted) and covers re-discovery triggers, token handling, and username semantics without redundancy or padding. Concise yet information-dense.

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 config tool with no output schema and significant side effects, this is quite complete: it covers state semantics, credential handling, discovery triggers, and usage context. The only minor gap is it doesn't state whether setting one parameter resets or preserves other previously-set values (partial-update semantics), which could matter for an agent reasoning about session state.

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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that providing base_url or username triggers credential re-discovery, listing the three discovery sources, the refresh idiom for base_url, and username's no-fallback narrowing. This is genuine value-add over the schema text, though some parameter details are already well-documented in the schema itself.

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 what the tool does: configures the Gitea connection at runtime with session-scoped, non-persisted semantics. It enumerates the specific parameters (base_url, owner, repo, username) and explicitly distinguishes this from every sibling, which are all resource CRUD operations (issues, comments, releases, etc.) — this has a clearly different purpose.

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?

The description provides explicit when-to-use guidance: 'Use this when the server started unconfigured or when you need to switch instances/identities mid-session.' It also conveys the 'I just added a git credential, refresh now' idiom in the schema parameter description. It doesn't explicitly name alternatives for when not to use, but no sibling serves the same purpose, so exclusion isn't critical here.

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