gblin-mcp-server

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile well. The description adds useful context by stating 'Cached' (stale-data behavior) and 'Public' (no auth/access requirements needed). No contradiction with annotations. It adds behavioral value beyond the 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?

A single sentence delivers purpose and key behavioral cues ('Public', 'Cached') with zero filler. Every word earns its place. The 'Cached' note is valuable and wouldn't be inferable from the schema or annotations.

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 no parameters and no required inputs, making it a simple call. An output schema exists, so return values needn't be documented in the description. The description covers purpose, access level, and caching. Adequate for a zero-input, read-only tool, though it could name the specific units or formats of the returned stats.

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?

There are zero parameters (0, 0 required), so the baseline of 4 applies — there's nothing for the description to clarify. The schema coverage is meaningful at 100% with an empty object, so no parameter documentation burden exists.

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 returns 'Public GBLIN agent-economy observatory stats' and lists specific data categories (x402 calls, payers, on-chain counters). The verb 'get' plus specific resource 'agent-economy stats' distinguishes it from siblings like get_market_risk_regime or get_protocol_info, though it doesn't explicitly name alternatives.

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 gives context cues like 'Public' and 'Cached' but doesn't explicitly state when to use this tool vs alternatives. The sibling set (attestation_sample, market_risk_regime, protocol_info) are semantically distinct enough that the purpose implies usage, but there's no explicit when/when-not 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating call. The description adds valuable behavioral context beyond annotations: it's FREE, static, permanently expired, and returns the same EIP-712 schema shape, which tells the agent exactly what to expect without invoking it.

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 a single sentence packed with dense, useful information: cost (free), recency (static), validity (expired), schema compatibility (identical EIP-712 shape), and usage intent (wire against then switch). Zero wasted words, maximum signal density.

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?

This is a zero-parameter, description-carrying tool with an output schema provided. The output schema handles return format documentation, annotations cover safety, and the description explains the purpose, limitations (expired, static), and migration path to paid. Completely adequate for the tool's simplicity and well-supported by structured metadata.

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?

There are 0 parameters, so the description carries no parameter documentation burden. Per the guidelines, 0 params yields a baseline of 4. The description appropriately emphasizes that no input is needed (static, sample, permanently expired) and the output shape is described, so nothing is undocumented.

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 this is a static sample of the Risk Attestation with identical shape and EIP-712 schema, distinguishing it from the paid endpoint. The verb 'get' + specific resource 'attestation_sample' with explicit 'sample:true, permanently expired' characteristics makes the purpose unambiguous and distinct from siblings like get_market_risk_regime and get_protocol_info.

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 explicit usage guidance: 'Wire your parser/verifier against this, then switch to the paid endpoint.' This tells the agent exactly when to use this tool (development/testing) and what the alternative path is (the paid endpoint, presumably accessed via how_to_buy_live_attestation). This is exemplary usage 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering the safety profile. The description adds behavioral value by stating 'Free,' that the output is unsigned (no attachable proof), and that it uses the same math as the paid attestation. It discloses the counterpart of what this tool does NOT provide (signed proof).

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, information-dense, zero filler. Every clause adds value: the output type, the source, the cost, the signing limitation, and the pointer to the paid alternative. Striking an excellent balance of completeness with 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 tool is simple (no parameters), has rich annotations, and an output schema exists, so the description doesn't need to explain return values. The description covers source, cost, unsigned nature, and the sibling path for signed proofs. Could add the supported symbols scope (BTC/ETH already mentioned) or staleness info, but this is complete for its simple footprint.

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 tool has zero parameters, so schema coverage is trivially 100%. The description establishes the output semantics by enumerating the possible regime values (calm | elevated | crash) and identifying the data source (GBLIN Crash Shield on Base mainnet), which meaningfully frames what an empty-parameter call returns.

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 reads the current BTC/ETH market risk regime from GBLIN's on-chain Crash Shield on Base mainnet, with explicit output values (calm | elevated | crash). It distinguishes itself from the paid signed attestation variant and names a related sibling (how_to_buy_live_attestation). Specific verb (read), resource (Crash Shield), and scope (BTC/ETH risk regime) are all present.

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 indicates this is the free/unsigned version to use when a signed proof is not required, and points to how_to_buy_live_attestation for the paid signed version. This gives clear context on when to use this tool vs the alternative, though it doesn't explicitly state 'use this tool when you only need live risk data without proof.'

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 are rich (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) and the description aligns without contradicting them. The description adds value by clarifying this is a static llms.txt-style reference document (free, protocol-level info) rather than dynamic market data. It also enumerates what content the overview covers, giving the agent expectations about the return payload.

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 a single sentence that packs meaningful content: the tool's purpose (overview), intended audience (agents/llms.txt), and the enumerated subjects it covers. Zero wasted words, front-loaded with the key noun phrase.

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 zero-parameter, static informational endpoint with strong annotations and a presence of an output schema, the description is largely sufficient. It enumerates what the overview contains. One minor gap: it doesn't note that this returns static/documented content vs live data, but the 'llms.txt' reference and free annotation largely convey that.

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?

There are zero parameters, so the baseline is 4. The description correctly implies no inputs are needed (it's a static overview endpoint). Nothing more is required here.

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 a GBLIN protocol overview for agents, listing the content areas (contracts, endpoints, prices, payment flow, field contract). The verb 'overview' and the 'for agents (llms.txt)' framing make the purpose specific. It doesn't explicitly differentiate from siblings like get_agent_economy_stats, but its scope (protocol-wide overview vs specific stats) is reasonably inferable.

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 this is for agents needing to understand the protocol (llms.txt reference) before engaging with other tools. It distinguishes itself as a top-level informational resource. However, it doesn't explicitly state when to use it vs alternatives or mention any exclusions, such as 'use get_market_risk_regime for market-specific state instead'.

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?

No annotation contradiction. The annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, confirming this is a safe read/informational operation. The description adds useful context beyond annotations: it specifies the price ($0.003 USDC), the chain (Base), the mechanism (x402), and the signing standard (EIP-712), plus the offline verification aspect. This provides meaningful behavioral context for an instructional tool even though annotations already convey safety.

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 a single, tightly-packed sentence that front-loads the core purpose (instructions for buying) and includes specific details (EIP-712, x402, $0.003 USDC, Base, offline verification) without waste. Every clause earns its place. It could potentially be split for scannability, but it's efficient and information-dense.

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 tool with 0 parameters, an output schema, and strong annotations, the description is reasonably complete. It explains the purpose and scope. However, it's an instructional tool with an output schema—the description could more explicitly signal the format/structure of the instructions returned (e.g., that it returns step-by-step guidance). The mention of offline verification is a good detail, but a slightly fuller description of what the returned instructions contain would improve completeness.

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?

There are 0 parameters, and schema description coverage is 100% (no parameters). With zero parameters, the baseline is 4 per the rubric. The description itself adds value by explaining what the returned content covers (buy instructions and offline verification steps), which is relevant since this tool output is instructional rather than data.

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 what the tool does: provides instructions for buying a live EIP-712-signed risk attestation over x402, including price and chain specifics. It's a how-to/informational tool rather than an action tool, and the verb 'Instructions for buying' is specific. It also adds a second function (verifying offline). It doesn't explicitly distinguish from siblings, but its purpose as instructional content is clearly distinct from data-fetching siblings like get_agent_economy_stats or get_market_risk_regime.

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 this is a how-to/instructional tool to consult before purchasing an attestation. It conveys the context (buying live EIP-712 attestation on Base for $0.003 USDC) but doesn't explicitly state when to use it vs alternatives or any exclusions. The sibling tools are all data-retrieval tools, so there's an implicit contrast, but no explicit guidance on when to choose this over them.

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