ponisha_api_get

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds two pieces of real value beyond that: 'authenticated' (the caller need not supply credentials) and 'Raw' (the response is passed through unprocessed rather than shaped into a tool-specific model). It says nothing about error handling, rate limits, or what a failure looks like for an open-world passthrough, which is the main remaining behavioral gap.

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?

A single sentence with no filler, and the two load-bearing facts — authenticated GET, and the not-covered-by-another-tool constraint — both land immediately. Nothing to trim.

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 generic passthrough with no output schema, the description covers the essentials but leaves two gaps an agent would want: how this differs from ponisha_api_request (presumably non-GET), and the shape of a raw response or error. Annotations carry the safety and open-world signal, which lowers the bar somewhat, but the tool's whole purpose is unrestricted endpoint access, so a bit more routing detail would help.

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 67%: 'path' carries an example and 'service' documents all three base URLs, so the schema does most of the work. The description adds nothing about parameters, and 'query' is entirely undocumented in both places — though as a standard pass-through map with propertyNames typed as string, its meaning is largely self-evident. Baseline 3 is appropriate.

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?

States a specific verb and scope ('Raw authenticated GET') plus the qualifying constraint 'against any Ponisha endpoint not covered by another tool', which is enough to distinguish it from the domain-specific siblings like ponisha_get_project. It stops short of naming ponisha_api_request, the obvious adjacent generic tool, so the boundary between the two is never explicitly drawn.

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?

'Not covered by another tool' implies a fallback role, which is a useful usage signal, but it is stated as a scope qualifier rather than a directive to prefer dedicated tools first. There is no guidance on when to pick this over ponisha_api_request, no mention of auth prerequisites, and no exclusions for endpoints this method cannot reach.

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