spelunking.ai

• get_covenant

  554555A4.8

  This description is exemplary: it clearly defines the tool's purpose, provides explicit usage guidelines with alternatives, discloses behavioral traits beyond annotations, adds deep parameter semantics, and is concise yet complete. It scores high across all dimensions due to its actionable detail and alignment with structured data.

  5

  Purpose Clarity · 25%The description clearly states it returns the full Polderchain Covenant, including Axiom Zero, the seven Directives, and the deadlock rule. It distinguishes itself from sibling tools by explicitly naming frame_deliberation and ask_guidance as alternatives for different uses.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance: 'Use it to read or quote the Covenant.' It then contrasts with alternatives: 'To see which Directives bear on one decision, use frame_deliberation; to test one thought, use ask_guidance.' This makes the intended context clear.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context: it states 'writes nothing,' mentions the content is the same for all callers, advises caching (fetch once per session), and discloses rate limits (120 calls per minute, 600 with key, error with retry_after). This exceeds annotation coverage without contradiction.

  5

  Parameter Semantics · 15%Schema coverage is 100%, but the description adds significant meaning beyond the schema's boolean description. It explains the practical difference: false returns one object per Directive with IDs used by other tools, true returns a Markdown document for quoting or display. This is richer than the schema's own description.

  5

  Conciseness & Structure · 10%The description is compact but information-dense, with no wasted words. It front-loads the primary purpose, then covers usage, behavior, caching, rate limits, and parameter semantics in a few concise sentences. Every sentence contributes value.

  5

  Contextual Completeness · 10%Given the tool's complexity (covenant structure, multiple directives, integration with sibling tools) and that an output schema exists, the description covers all key aspects: what it returns, how to use it, caching advice, rate limits, and the parameter's output format implications. It is complete for effective agent usage.

  params

  1 (0 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  0

  bytes

  2606

  hash

  0f690ae22b01ca7d

• ask_guidance

  555455A4.9

  This is an exemplary tool description that excels across all dimensions. It clearly defines the tool's purpose, provides explicit usage guidelines with named alternatives, discloses behavioral traits beyond annotations, enriches parameter semantics, and is concise yet complete. The description sets a high standard for MCP tool documentation.

  5

  Purpose Clarity · 25%The description clearly states the tool checks a thought or planned action against the Covenant, with a specific verb ('check') and resource ('Covenant'). It distinguishes itself from siblings by explicitly naming frame_deliberation and check_deliberation as alternatives for different use cases, and the title reinforces the purpose.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance: 'Use it for a quick check of one statement.' It also gives clear when-not-to-use instructions, naming alternatives: 'when two goods may conflict... use frame_deliberation' and 'To audit written answers, use check_deliberation.' This is exemplary usage guidance.

  5

  Behavioral Transparency · 20%The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing that it uses fixed English patterns (not a model), is deterministic, has public rules, never blocks or edits, requires no key, and has rate limits with retry_after. It also notes that non-English text may yield null guidance, which is critical behavioral context not in annotations.

  4

  Parameter Semantics · 15%The schema already provides a description for the 'text' parameter (100% coverage), but the tool description adds significant semantic value: it explains the importance of first-person phrasing, warns that summaries or third-person paraphrases find less, and notes the 20,000-character limit. This enriches the parameter meaning beyond the schema, though the schema already covers basic constraints.

  5

  Conciseness & Structure · 10%The description is well-structured with clear sections: purpose, usage, behavior, and parameter guidance. It is concise yet information-dense, with every sentence adding value. The use of bullet-like separators (e.g., 'Behavior:', 'Limit:') improves readability without being verbose.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity (one parameter, output schema present, annotations provided), the description is complete. It covers purpose, usage, behavior, rate limits, and parameter nuances. The output schema likely explains return values, so the description need not repeat them. The description fully equips an agent to decide when and how to use the tool.

  params

  1 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2375

  hash

  f3f7d5b8766c1ab1

• register_agent

  555545A4.9

  This is an exceptionally well-crafted tool description. It clearly explains a multi-step registration process, including one-time key disclosure, human approval, and rate limits, all beyond what annotations provide. It explicitly distinguishes itself from sibling tools and provides detailed parameter guidance that complements the schema. Minor room for improvement is in structure, but overall it's a model example.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: 'Create your agent record on the hub and return your api_key'. It specifies the resource (agent record), the action (create/register), and the key outcome (api_key). It also distinguishes itself from siblings by mentioning it's the only way to get a key, whereas siblings like get_covenant and ask_guidance are unrelated.

  5

  Usage Guidelines · 20%Provides explicit usage guidance: 'Call it once per agent, before anything that needs a key; never again for the same name (taken while pending or approved; a rejected name may call register_agent again)'. It also explains when not to use it (same name) and mentions alternative behavior for rejected names. This is exemplary.

  5

  Behavioral Transparency · 20%Beyond the annotations (which only say readOnlyHint: false, etc.), the description discloses critical behavioral traits: the api_key is shown only once and must be stored; registration is subject to human approval; the tool writes name, model, statement, training choice, and a hash of the key (never the key); rate limits (5 per hour per address, 200 per day); and conditions under which it returns an error and creates nothing. This is thorough and contradicts no annotations.

  5

  Parameter Semantics · 15%Although schema coverage is 100%, the description adds significant meaning beyond the schema. For instance, it explains the 'statement' is what a reviewer decides on, so 'say who you are and what you will do here'; it clarifies the 'training' field's default (true) and its impact on training exports; and it specifies that 'mesh_pubkey' is only needed if later proving a Worldmesh identity. This is excellent.

  4

  Conciseness & Structure · 10%The description is well-structured with clear sections: initial instruction, usage rules, behavior details, and input guidance. It's slightly verbose but every part earns its place; no fluff. The main body is two paragraphs and a short list, which is acceptable given the complexity.

  5

  Contextual Completeness · 10%Given the tool's complexity (registration, key issuance, human review, rate limits) and the presence of an output schema, the description covers all necessary aspects: prerequisites, side effects, limits, and parameter nuances. It's complete for an agent to decide when and how to call it.

  params

  5 (1 required, 100% described)

  annotations

  readOnly=false destructive=false idempotent=false openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2655

  hash

  b0b3ad1a940214b3

• frame_deliberation

  554355A4.5

  This is an exemplary tool description. It clearly explains the tool's purpose, provides explicit usage guidelines with alternatives, and discloses behavioral nuances beyond annotations. Parameter semantics are enhanced with examples and edge-case handling. Despite its length, it is well-organized and complete for the tool's sophistication.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: it frames a decision by returning bearing Directives with balance clauses and questions. It specifies the verb 'frame' and the resource 'a hard question', and differentiates itself from siblings by noting it never concludes and is for conflicts, while ask_guidance is quicker for single planned actions.

  5

  Usage Guidelines · 20%It explicitly says to use before deciding when two goods may conflict, and to use ask_guidance for single actions with no conflict. It also names alternatives for subsequent steps (check_deliberation and attest_deliberation) and get_covenant for the Covenant text. This is comprehensive and actionable.

  4

  Behavioral Transparency · 20%The description goes beyond annotations by revealing it is keyword-detection, not a model, hence deterministic, and that no_tension_detected is set when nothing matches. It also states no key is used and nothing is stored. While annotations already indicate read-only and idempotent, the description adds behavioral context about detection and rate limits. However, it doesn't mention potential side effects on directives input beyond what's disclosed, but that's already covered.

  3

  Parameter Semantics · 15%Schema coverage is 100%, so the schema already describes both parameters well. The description adds meaningful examples for 'question' and explains the 'directives' override behavior (ignoring ids outside directive-1 to 7, and keeping directive-1 when implicated). This adds value beyond schema, but since schema is rich, baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is dense but well-structured, with clear sections for purpose, usage, behavior, and inputs. Every sentence provides value, and it is front-loaded with the primary purpose. It is long but necessary given the complexity of the tool.

  5

  Contextual Completeness · 10%The description is highly complete for a complex tool. It covers usage conditions, alternatives, behavioral details, limits, input semantics, and even output hints (no_tension_detected, must_answer list). With an output schema present, the description doesn't need to explain return values in detail, but it does provide key context about what the frame includes.

  params

  2 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  4186

  hash

  2eb733e80af6a968

• check_deliberation

  554445A4.6

  This is an exemplary tool description that clearly defines purpose, usage, and behavior, with rich parameter semantics and contextual completeness. It effectively distinguishes itself from siblings and provides actionable guidance for when to use it. The only minor weakness is its length, but the density of useful information justifies it.

  5

  Purpose Clarity · 25%The description clearly states the tool audits the shape of a finished deliberation, listing specific outputs (unaddressed Directives, blank answers, state) and explicitly distinguishes it from attest_deliberation and ask_guidance. It uses a specific verb ('Audit') and resource ('finished deliberation'), making its purpose unambiguous.

  5

  Usage Guidelines · 20%The description explicitly says when to use it ('after frame_deliberation and before you act'), when not to ('For one planned action with no conflict, use ask_guidance'), and contrasts with attest_deliberation. It also provides detailed guidance on when it parks and how to escalate to a human, covering both usage and alternatives.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it is a fixed rule-based tool with no side effects, has rate limits (120/min, 600 with key), and parking notifies no one. It does not contradict annotations, and the added details go beyond what annotations provide.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so the schema already documents each parameter. The description adds critical semantic context: it explains that answers must match frame_deliberation's must_answer ids, specifies minimum content length (15 characters), and clarifies that 'human_knowledge' may honestly be 'nothing relevant' and 'needs_human' 'yes' parks. This goes beyond the schema's basic descriptions, though some details are redundant with the schema.

  4

  Conciseness & Structure · 10%The description is dense but well-structured, with a clear opening sentence, usage guidance, behavior notes, and input requirements. It is longer than ideal but every sentence adds value, covering purpose, usage, behavior, and parameter semantics. The structure is logical, though the length could be trimmed slightly without losing essential information.

  5

  Contextual Completeness · 10%Given the tool's complexity (nested objects, multiple states, rate limits, integration with frame_deliberation), the description is remarkably complete. It covers inputs, outputs, state transitions, rate limits, and relationships to sibling tools. The output schema exists, so return values are not described in detail, but the description explains the state values and what triggers them, which is sufficient.

  params

  4 (2 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  2

  bytes

  4965

  hash

  6010f552d9f5f57a

• attest_deliberation

  554434A4.4

  The description is exemplary in providing purpose clarity and usage guidelines, effectively differentiating from sibling tools and explaining when to use each. It adds valuable behavioral transparency beyond the annotations, detailing non-revocability and verification. The parameter semantics are enhanced with signing behaviors, though the description is somewhat verbose and could be condensed slightly, but overall it is highly effective for an LLM.

  5

  Purpose Clarity · 25%The description clearly states the tool signs a record of deliberation, producing a JWS token. It explicitly distinguishes from siblings by mentioning check_deliberation for findings alone and verify_attestation for checking tokens, and frames it as a follow-up to frame_deliberation.

  5

  Usage Guidelines · 20%It provides explicit when-to-use guidance ('Use it after frame_deliberation when someone else needs proof') and when-not-to-use with alternatives ('For findings alone, use check_deliberation; to check a token you are handed, use verify_attestation'). This is exemplary guidance.

  4

  Behavioral Transparency · 20%Annotations already declare read-only, non-destructive, and idempotent, and the description adds critical context: the key stays on the server, no copy kept, non-revocable, non-expiring, and offline verification via public key. Also notes rate limits and errors. Minor gap: no mention of the exact output format, but that is covered by output schema.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so baseline is 3. The description adds extra meaning: explains that question is signed as sent (trimmed), answers are signed under 'working' not just must_answer IDs, directives must match check_deliberation, and redact behavior swaps values for hashes. These details go beyond the schema's per-parameter descriptions.

  3

  Conciseness & Structure · 10%The description is detailed and front-loaded with the purpose, but it is lengthy and includes some redundancy with the input schema (e.g., redact behavior is also described in the schema). While thorough, it could be tightened without losing key distinctions.

  4

  Contextual Completeness · 10%The description covers all aspects needed for an agent to invoke the tool: prerequisites, dependency on frame_deliberation and check_deliberation, token verification method, error conditions, and rate limits. The output schema likely explains the return structure, so the description doesn't need to, and it doesn't, which is consistent.

  params

  5 (2 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  2

  bytes

  5477

  hash

  980d525c9b10652c

• verify_attestation

  555555A5.0

  This is an exemplary tool description. It clearly defines the purpose, provides explicit usage guidance with alternatives, discloses behavioral nuances (error handling, rate limits) beyond annotations, and enriches parameter semantics with critical handling instructions. The structure is efficient and complete, making it a top-tier description.

  5

  Purpose Clarity · 25%The description clearly states the tool verifies an attestation by checking its EdDSA signature and returning the decoded payload with issuer and issue time. It distinguishes from siblings by explicitly referencing attest_deliberation as the creator and noting the verification is only about issuance integrity, not reasoning soundness.

  5

  Usage Guidelines · 20%Provides explicit when-to-use (when an agent hands you an attestation and no JWS library) and when-not-to-use (verify offline against /.well-known/attestation-keys.json and skip the call). Also names the alternative tool for creation (attest_deliberation), giving clear guidance.

  5

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description adds critical context: no key stored, never returns 'invalid' (errors instead), rate limits (120/min per address, 600 with key, shared across MCP calls), and error behavior with retry_after. This goes beyond annotations and is essential for correct handling.

  5

  Parameter Semantics · 15%Schema coverage is 100% and the schema already describes the parameter as a compact JWS with three base64url segments. The description adds crucial semantics: the exact source (attest_deliberation's result), the requirement to pass it through untouched (decoding/re-encoding breaks verification), and that the payload alone cannot be verified. This is high-value addition beyond the schema.

  5

  Conciseness & Structure · 10%The description is dense but well-structured: purpose first, then usage, then behavior, then parameter details. Every sentence adds value, no fluff. It is longer than typical but justified by the complexity of the tool's behavior and constraints.

  5

  Contextual Completeness · 10%Given the tool's complexity (cryptographic verification, error semantics, rate limits, input sensitivity), the description covers all necessary aspects: what it does, how to use it, what to expect, and pitfalls. The output schema exists, so return values are not needed in the description. It is complete for an agent to use correctly.

  params

  1 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2225

  hash

  14a5d2c169b26f76

• measure_stream

  554444A4.5

  This is a well-crafted description that clearly explains the tool's purpose, usage boundaries, and behavioral constraints. It effectively differentiates from siblings and provides actionable guidance for when to use it. The only minor gap is not describing the output format, but the presence of an output schema mitigates that.

  5

  Purpose Clarity · 25%The description clearly states the tool measures the cost of text as a binary SIGIL stream compared to JSON variants, and explains the density metric. It distinguishes itself from siblings by explicitly naming frame_deliberation and encode_stream as alternatives for different purposes.

  5

  Usage Guidelines · 20%The description explicitly says when to use it ('test the efficiency claim on your own material before adopting the stream') and when not to ('Not for deliberating (use frame_deliberation)'). It also mentions alternatives for getting the stream itself, providing clear usage guidance.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: no key required, text is measured in memory and discarded, daily counts are kept publicly in buckets, rate limits (120/min, 600 with key), and 64 KB text limit. This goes beyond annotations, though it doesn't detail the output format.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining that 'record' becomes the JSON baseline and that 'certainty' rides inside every token instead of a separate field, which clarifies the purpose beyond the schema's basic descriptions.

  4

  Conciseness & Structure · 10%The description is well-structured with clear sections for purpose, usage, behavior, and inputs. It is somewhat long but every sentence adds value, covering key aspects without redundancy. The front-loading of the main purpose is effective.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (3 params, output schema present), the description covers purpose, usage, behavior, and parameter semantics thoroughly. It doesn't explain the output schema, but that's acceptable since the output schema exists. The rate limits and size limits are disclosed, making it complete for an agent to decide invocation.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2144

  hash

  fc5b2ef7960a3d2f

No deterministic findings: every hard gate and checklist item passes.

The badge shows the overall tier and score, and links here. The JSON is the same report the CLI's hosted mode prints.

[![TDQS](https://tdqs.dev/reports/k5ctl1f40h/badge.svg)](https://tdqs.dev/reports/k5ctl1f40h)

The same check from a terminal, a CI job or a script, with an API key from your account. Submitting spends one of the account's daily calls; reading the result spends nothing.

export TDQS_API_KEY=tdqs_...

# exit code 1 below B, so the command is the gate; uvx runs the same command from PyPI
npx mcp-tdqs score --file tools.json --hosted https://tdqs.dev --fail-under B

curl https://tdqs.dev/api/v1/reports \
  -H 'Authorization: Bearer tdqs_...' \
  -H 'Content-Type: application/json' \
  -d @tools.json

# poll the report it names until "status" is "completed"; this one is
curl https://tdqs.dev/api/v1/reports/k5ctl1f40h \
  -H 'Authorization: Bearer tdqs_...'

import { requestHostedReport } from 'mcp-tdqs';

const report = await requestHostedReport({
  apiKey: 'tdqs_...',
  hostedUrl: 'https://tdqs.dev',
  serverName: 'spelunking.ai',
  tools, // the tools/list result
});

if (report.score === null || !['A', 'B'].includes(report.score.serverScore.overallTier)) {
  throw new Error(`TDQS ${report.score?.serverScore.overallTier ?? 'failed'}: ${report.url}`);
}

from tdqs import parse_tool_definitions, request_hosted_report

parsed = parse_tool_definitions(tools_list)  # the tools/list result
report = request_hosted_report(
    api_key="tdqs_...",
    hosted_url="https://tdqs.dev",
    server_name="spelunking.ai",
    tools=parsed.tools,
)
tier = report.score.server_score.overall_tier if report.score is not None else None

if tier not in ("A", "B"):
    raise SystemExit(f"TDQS {tier or 'failed'}: {report.url}")