PPN Hub — public APIs over MCP

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

With no annotations, the description compensates by disclosing key behaviors: it fans out to multiple APIs, returns merged JSON, handles partial results with an errors[] list, and requires authorization. This is substantial transparency, though it omits details like rate limits or latency.

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 very concise with three sentences, each adding essential information: behavior, error handling, and authentication. No redundant or vague phrasing.

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 lack of output schema and annotations, the description covers the main functionality and error reporting, but does not describe the structure of the merged JSON output or any constraints on usage, leaving some aspects incomplete for an agent.

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 100% and descriptions in the schema already explain lat, lon, and place adequately. The tool description adds no new semantic information beyond what the schema provides, so the default score of 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?

The description clearly states it provides an 'Environmental brief for one location' by aggregating multiple APIs, and the name 'environment_brief' reinforces this. It distinguishes from the broader sibling tools 'execute_api' and 'search_apis' by being specialized and self-contained.

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 it requires a specific authorization token, but does not explicitly state when to use this tool versus alternatives, nor provides any exclusion criteria. Usage is implied for environmental data retrieval but lacks explicit guidance.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses the authentication requirement (Bearer token) and implies side effects via 'execute a request,' but lacks details on error behavior, rate limits, or whether it is read-only or mutating. This is minimal but non-contradictory.

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 two sentences, immediately states the core purpose, and avoids redundancy. It front-loads the primary action and follows with critical usage guidance, with zero wasted words.

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 generic nature (any of 59 APIs) and no output schema, the description covers essential aspects: purpose, prerequisite discovery, and auth. However, it omits expectations about response format or error handling, which are critical for a generic executor. It is adequate but lacks completeness for high-variance behavior.

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 100%, so the schema already documents all parameters. The description adds little beyond the schema; it repeats the instruction to use search_apis but does not enrich parameter meaning. The baseline of 3 is appropriate because the schema does the heavy lifting.

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: 'Execute a request against any of the 59 registered APIs.' It uses a specific verb+resource pattern and distinguishes itself from siblings by clarifying its role as the executor, while search_apis is for discovery.

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 explicitly instructs to 'Use search_apis first to find the correct api name and operationId,' providing clear prerequisite guidance. It also notes the required authorization header, which is essential for correct invocation. This covers when to use the tool and implies alternatives for discovery.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It explains what the tool returns (matching endpoints with method, path, summary, parameters, example) and the presence of a 'coverage' field for region-limited APIs. It does not explicitly state that it is read-only, but as a search tool it is inherently non-destructive. The description adds useful context beyond the schema, such as the region filter behavior ('Returns region-specific + global APIs; excludes APIs limited to other regions'), which enhances transparency. Missing explicit read-only statement is a minor gap but not a contradiction.

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 and information-dense, consisting of two sentences that cover the scope, result structure, usage guidance, and a key behavioral note. Every sentence adds value, and it is front-loaded with the most important information. There is no redundancy or fluff.

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?

The tool has 6 parameters, 1 required, and no output schema, so the description must convey the return value and usage context. It does explain what is returned and mentions the 'coverage' field and region filter. It does not explicitly mention pagination or the limit parameter, but since the schema documents limit with its default and maximum, that gap is acceptable. The description is complete enough for an agent to use effectively in conjunction with the sibling tools.

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 schema has 100% coverage for all 6 parameters, so the baseline is 3. However, the description adds significant meaning beyond the schema: it explains that the query matches 'operationId, summary, description, path, API name, tags; synonyms expanded,' which is not in the schema. It also elaborates on the region filter's behavior regarding global versus region-specific APIs. These additions give deeper semantics for key parameters, justifying a score above baseline.

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: 'Search across 484 endpoints in 59 APIs...' and specifies it returns matching endpoints with method, path, summary, parameters, and an example. It explicitly distinguishes itself from siblings by stating 'Use this to discover available API endpoints before calling execute_api.' This provides a specific verb (search) and resource (endpoints across APIs), and a clear distinction from the sibling tools.

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 explicitly says when to use it: 'Use this to discover available API endpoints before calling execute_api.' It also gives usage guidance for the region filter: 'Results carry a "coverage" field... use the "region" filter to narrow.' This is direct and clear about the context of use, fulfilling the dimension completely.

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