Swagger: Get Portal

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

The description provides no behavioral traits beyond what is already declared in annotations (readOnlyHint, idempotentHint, destructiveHint). It does not add any information about side effects, authentication requirements, or rate limits, which are minimal but expected for a read operation.

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 short and includes the key parameter list, though it redundantly repeats the schema. It is front-loaded with the main action and avoids unnecessary detail.

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 that the tool is a simple get operation with only one required parameter, the description is adequate. The presence of an output schema reduces the need to describe return values, and no additional context (e.g., pagination, error handling) is essential for this straightforward use case.

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 description lists the parameter and its description exactly as in the input schema. Since schema coverage is 100%, the description adds no new meaning beyond what the schema already provides, meeting the baseline for 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 description uses a specific verb ('Retrieve') and resource ('information about a specific portal'), and it contrasts with sibling tools like swagger_list_portals (list all portals) and swagger_update_portal (modify a portal).

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 implies the tool is used to get details of a single portal, but it does not explicitly state when to use this versus swagger_list_portals or other portal-related tools, nor does it mention any context or exclusions.

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