Get instance info

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

Despite annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds significant behavioral nuance: it authenticates on every call rather than caching, describes what 'features' represents (server version vs user permissions), and explains error semantics (401 vs network error) with actionable hints. This goes beyond the annotations.

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: it opens with a clear purpose, then provides usage triggers, a concise list of return values, pitfalls, and alternatives. Each sentence adds unique value. Despite its length, it is tightly written and front-loaded with the most critical information.

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?

Although the tool has no parameters and a rich output schema, the description fully explains when to use it, what it returns, why it should be called first, how to interpret failures, and how it differs from related tools. There is no gap in context for an agent to infer from the schema alone.

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, so there is nothing for the description to explain about parameters. The schema coverage is trivially 100%. The description does add substantial value by detailing the return fields (version, name, attachment size, user info, features), which compensates for the lack of parameter-level semantics. The score is a baseline 4 because with no parameters, the description cannot earn full marks in this dimension.

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's purpose: "Check the OpenProject connection and report what this instance supports." It uses specific verbs (check, report) and a specific resource (instance info). It also distinguishes itself from sibling tools by explicitly pointing to get_project_metadata and list_permissions for related but different information.

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?

Provides explicit when-to-use guidance: "Call this first when anything fails in an unexplained way, when the user asks 'am I connected / who am I', or before using a version-gated parameter." It also names alternatives for per-project metadata and user permissions, making the usage context crystal clear.

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