get_r_asset_asset_ports_id

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

No annotations are provided, so the description must compensate. It does not disclose the return format (though an output schema exists), error conditions, authentication requirements, or any side effects. It only states the HTTP call semantics, which is minimal behavioral context for a GET 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 concise but only partially front-loaded; it starts with the action and endpoint but quickly becomes generic. The sentence about parameter placement is useful but could be more specific. It is not overly verbose, but it could be restructured to present key details (e.g., expected path param) more prominently.

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 the simple structure (no nested objects, output schema present), the description is still inadequate because it lacks details on the exact path parameter name (e.g., 'id'), the shape of the query filters, and the response structure. An agent would have to infer too much from the endpoint itself.

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 description coverage is 0%, so the description must explain parameters. It provides only generic guidance (route IDs in path_params, filters/pagination in query, headers in headers) but does not list specific parameter names or their types. This is a baseline level of compensation for the coverage gap.

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 states the verb 'Retrieve' and the resource 'asset port' (assumed from the tool name), and it identifies the endpoint. However, it does not fully clarify what an 'asset port' represents or differentiate it from the sibling tool get_r_asset_asset_ports (without ID). The description is a near-restatement of the tool name and endpoint, providing minimal added clarity.

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 mentions how to structure the request (path_params, query, headers) but does not specify when to use this tool versus the sibling get_r_asset_asset_ports (the list tool) or other related tools. It implies use for retrieving a single asset port by ID but does not state prerequisites or exclusions.

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