PubFi MCP

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds one genuinely useful trait — the result is bound to the 'installed Registry generation', implying a versioned snapshot — but says nothing about failure behavior for unknown ids or whether results can go stale.

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 front-loaded sentence with no filler, though it is dense with internal jargon ('metering', 'readiness contract', 'Registry generation') that costs readability without being explained.

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?

An output schema exists, so return values need not be described, and the description correctly signals the payload's scope and its tie to a registry generation. Only error/unknown-id behavior is left unaddressed for a tool whose sole input can easily be wrong.

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?

One parameter with 100% schema description coverage, so the schema already carries the format, pattern and provenance ('id returned by pubfi.capabilities.list'). The description reinforces 'exact' but adds no syntax or semantics beyond that, matching the 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?

States a specific verb (Return) and a specific resource (the full typed request/response/metering/readiness contract for one capability id). The phrase 'one exact capability id' implicitly contrasts it with the enumerating sibling pubfi.capabilities.list, so an agent can distinguish them without opening a schema.

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 never says when to call this instead of pubfi.capabilities.list, nor what happens with an unknown or stale id. The only routing hint ('id returned by pubfi.capabilities.list') lives in the schema, not the description.

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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so safety is fully covered. The description adds genuinely useful behavior beyond that: the result is deterministic, paged, unranked, and non-inferential, which tells an agent results are exhaustive rather than relevance-ordered. It still omits pagination mechanics and cursor-invalidation behavior that the schema only hints at ('generation-bound').

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?

Two sentences, zero filler, with the core enumeration guarantee front-loaded and the exclusionary semantic clause following. 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?

An output schema exists, so return shape needn't be explained, and annotations cover the safety profile. The description leaves an agent knowing it gets the whole catalog in deterministic pages with no ranking. The only modest gap is that the filtering parameters and cursor lifecycle are not contextualized in prose.

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 75% and the schema documents limit, cursor, and provider_key (explicitly noting provider_key is a static filter, not semantic search). The description adds nothing about any of the four parameters, so baseline 3 applies; the undocumented 'method' parameter is not compensated for in prose.

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?

Specific verb ('Enumerate') plus specific resource ('the complete installed Registry v2 catalog') with a stated output form ('deterministic compact pages'). It does not name any sibling, so the differentiation from pubfi.capabilities.get or pubfi.route.execute is left to inference.

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 server does not rank, infer intent, or choose a capability' implies this is the raw-catalog path as opposed to a semantic/dispatch path, which hints at when to use it. However, no alternative tool is named and no explicit 'use this when' condition is given, so guidance remains implied rather than actionable.

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?

Annotations indicate destructiveHint=true and idempotentHint=false, which the description does not contradict. The description mentions 'execute' and a conditional 'Append :free' behavior, adding some transparency beyond the annotations. However, it does not describe side effects, idempotency implications, or what happens on failure, leaving gaps in understanding the full behavioral impact.

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 dense, using jargon and a single complex sentence. It is not broken into clear parts and lacks a structured presentation of the tool's behavior and nuances. While not verbose, it sacrifices clarity for brevity.

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 description leaves out critical contextual details: it does not mention expected return values, error handling, or how the conditional free variant affects the request or response. Given the tool's apparent complexity (route execution, account scoping, conditional behavior), the description is insufficient for an agent to predict outcomes reliably beyond the basic execution.

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 provides descriptions for some parameters (body, query, raw_path), but the tool description does not explain any parameter semantics itself. It only mentions the overall execution behavior, not how the parameters like method, request_id, or idempotency_key are used. The schema coverage is partial, and the description adds no parameter-level detail, making it hard for an agent to construct a correct request.

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 executes a GET or POST path through an authenticated account lane, using the same matcher/executor as the HTTP gateway. This conveys the core purpose, though it relies on domain-specific jargon like 'PubFi account lane' and 'Registry v2 matcher.' It is distinguishable from the sibling read-only tools, which are for capabilities.

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 provides only conditional guidance ('Append :free only when the capability catalog publishes that exact account-scoped free variant') but does not explain when to choose this tool over alternatives or when not to use it. There is no explicit when/when-not context, leaving the decision largely to the agent's interpretation.

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?

The description goes beyond the annotations by revealing important side effects: the server streams and discards provider runtime code, persists only a compact proof, and returns independent comparison evidence. It also signals the authenticated account lane, which is useful context not present in the schema.

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 three tight sentences, front-loads the core verification operation, and then adds the most important input caveat and server behavior. Every sentence contributes essential information without repeating clues already in the schema.

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 description covers the core action, the key hash semantics, authentication context, and server-side storage/return behavior. It is complete except for deeper context around parameter semantics and explicit when-to-use conditions, which prevents a perfect score.

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 only 33%, so the description needed to explain the parameters; it adds the critical distinction for expected_authorized_code_hash as the Blake2b-256 hash of the payload, not the active code hash. However, it does not explain the meaning of network, extrinsic_hash vs extrinsic_index selection, request_id, or idempotency_key, leaving those gaps to the agent.

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 names a specific operation and resource: it verifies one reviewed Substrate System.apply_authorized_upgrade extrinsic. This is more precise than the sibling tools, which are generic capability discovery and routing 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 implies when it should be used by saying 'reviewed extrinsic' and by demanding the expected authorized upgrade hash rather than the active code hash. It does not explicitly state when to prefer this tool over alternatives or list exclusions, so usage guidance remains implicit rather than fully specified.

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