Call a Blackboard API endpoint directly

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

Annotations already carry readOnlyHint=false and openWorldHint=true, so the description need not repeat those. It adds useful context beyond them: the raw JSON return format, that the Ultra internal API exposes more than this server models, and the 'escape hatch' nature implying caution. It does not explicitly warn about destructiveness, but the schema's method enum and the note that writes need to be enabled supply that. No contradiction between description and 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?

Four sentences with no filler. The first sentence establishes the core purpose and return type; the second gives the primary usage condition; the third points to the broader API; the fourth instructs a preliminary step. Every sentence earns its place, and key guidance is front-loaded.

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 tool's open-ended nature, the description is sufficiently complete. It explains when to use it (no dedicated tool), how to discover wrapped endpoints (bb_list_endpoints), and what the response looks like (raw JSON). The schema covers parameters, and annotations cover the write/open nature. It does not describe error handling, but that is not essential for an escape-hatch tool and is not expected at this level.

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 100%, so each parameter (path, body, query, method, maxChars) already has a clear description. The tool description does not add extra parameter-level detail, but it maps conceptually to the 'any API path' idea. Per the rubric baseline of 3 for high schema coverage, this 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?

The description clearly identifies the tool as an 'escape hatch' that issues a request against any Blackboard API path and returns raw JSON. It distinguishes itself from the many sibling tools by being the generic fallback when no dedicated tool exists. The verb 'issues a request' plus the resource 'any Blackboard API path' is specific and unambiguous.

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?

It explicitly states when to use it: 'Use this when no dedicated tool covers what you need.' It also provides a concrete step ahead of use: 'Call bb_list_endpoints first to see what is already wrapped,' giving the agent a clear decision path and avoiding redundant calls.

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