SaSame MCP Observatory + Gold Rush Town

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description discloses key behaviors: SaSame records each statement, requires matching statements from both parties to produce a signed receipt, and does not move funds or verify off-chain settlement. This adds significant value beyond structured fields.

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 four sentences, concise and front-loaded with the main action. Every sentence adds value, with no superfluous 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 no output schema, the description explains the recording and condition for signed receipt, but does not specify the tool's return format or error states. It is mostly complete for a signing tool.

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 description adds meaning for settlement_ref ('use a chain/processor receipt') and role ('buyer or provider'), but with 25% schema coverage and no detail on signature_base64 or work_order_id, it only partially compensates for the lack of parameter descriptions.

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 that the tool is for signing a settlement statement for an agent transaction receipt, using specific verbs and resources. It distinguishes from siblings like agent_invoice_issue (which issues invoices) and agent_invoice_status (which checks status) by focusing on settlement attestation.

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 context on when to use it: both buyer and provider must sign, and it advises using a chain/processor receipt for settlement_ref when available. It does not explicitly state when not to use it or compare to alternatives, but the usage context is clear.

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 idempotentHint=true, and the description adds that the provider signs provider_receipt_challenge and that the receipt binds mutually accepted terms. This goes beyond annotations without contradiction. Could mention if any state changes occur.

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, each adding value: purpose, legacy clarification, signing mechanism, and exception for SaSame's own services. No redundancy.

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?

Purpose is clear but parameter details are lacking (33% schema coverage). No output schema, but description does not hint at return value. Adequate for basic understanding but incomplete for full automation.

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 only 33% (only external_invoice_ref described). The description does not clarify work_order_id or signature_base64 beyond names. It mentions provider signs a challenge but does not link to signature_base64 format or expected input.

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 explicitly states it issues a SaSame SRL-signed THIRD-PARTY AGENT TRANSACTION RECEIPT after provider delivery, distinguishes it from a fiscal/tax invoice, and clarifies the legacy name. This specificity differentiates it from sibling tools like agent_invoice_attest_settlement and agent_invoice_status.

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 explains when to use (after provider delivery) and when not to (for SaSame's own services, use separate accounting rail). It does not explicitly list alternative sibling tools but provides clear contextual boundaries.

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 provide readOnlyHint=true. Description adds that it returns a SaSame-signed statement and clarifies it's not a fiscal invoice. It also explains data retention policy (SHA-256 commitments). No contradiction with 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?

Description is verbose with extraneous details about SaSame and data storage policies. Front-loaded with main action but includes unnecessary digressions.

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?

Missing output schema description; does not specify return format of the signed statement. Given many sibling tools, lacks context for selection. Does not cover parameter constraints or examples.

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 has one parameter 'work_order_id' with no description. The tool name implies what it is, but description does not elaborate on format or examples. Baseline score due to single, obvious parameter.

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?

Description states it reads privacy-minimized state and returns a signed statement. Clear verb 'Read' and resource 'agent transaction receipt/work order'. However, it includes tangential details about SaSame architecture that dilute focus.

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?

No explicit guidance on when to use this tool versus siblings like 'receipt_state' or 'work_order_accept'. Does not specify prerequisites or exclusions.

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 provide readOnlyHint: true, so the description's 'Read-only; no external action is triggered' confirms that but adds no new behavioral details beyond what the annotations supply. No additional context about rate limits, auth, or side effects is given.

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 extremely concise with two sentences, no redundancy, and front-loads the core purpose. Every word adds value.

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 simple read-only tool with one parameter, the description covers the basic purpose but lacks details about the return format (no output schema), parameter enumeration completeness, and edge cases. It is adequate but has gaps.

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 0%, so the description must compensate. It lists some enum values ('claim', 'interest', 'plans', 'monitoring') but omits 'all' and 'correction', and does not explain the parameter's role or how to use it. The partial mapping provides some meaning but is incomplete.

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 uses the verb 'return' and specifies the resource as 'public next-step links for MCP Passport claim, interest, plans, and monitoring paths'. It clearly distinguishes the tool from siblings like analytics_public_export and analytics_public_summary by stating what it returns.

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 the tool should be used when public next-step links are needed, but it does not explicitly state when to use it over alternatives or provide any exclusions or context for when not to use it.

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. Description adds minor context about public nature but doesn't disclose additional traits like rate limits or data freshness.

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 concise sentences with no fluff. Front loads the key action and resource.

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?

Despite no output schema, the description indicates a 'manifest' is returned. More detail on what the manifest contains would enhance completeness, but current level is adequate for a simple read-only tool.

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 has zero parameters, so no additional meaning is needed. Baseline score of 4 applies as the description doesn't waste space on parameters.

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 a 'public aggregate analytics export manifest' and explicitly excludes private owner analytics, distinguishing it from other analytics tools in the context.

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 hints at when not to use ('No private owner analytics') but does not explicitly suggest alternatives among siblings like analytics_public_summary or analytics_next_steps.

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, so the description's addition of 'public' and 'outside-in' provides some context but does not disclose deeper behavioral traits like data freshness or rate limits. The description adds moderate value.

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 with no wasted words, front-loading the main action and efficiently covering behavior.

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 no output schema, the description explains what is returned (analytics summary) but could be more specific about content. Still adequate for a read tool.

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?

With 0% schema description coverage, the description adds meaning by explaining that url/mcp_id select a specific summary and omitting them returns a global summary, clarifying the parameters' role.

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 a public analytics summary, with specific verb 'Read' and resource. It distinguishes behavior with vs without arguments, and separate from sibling tools like analytics_public_export.

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 explains when to use with url/mcp_id vs without, providing clear usage context. However, it does not explicitly mention when not to use or alternatives, but the context is sufficient.

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?

Even with annotations readOnlyHint=true, the description adds extensive behavioral detail: it specifies the exact protocol steps ('server/discover with legacy initialize fallback, tools/list, and one read-only tool call over POST JSON-RPC'), what it measures and does not measure ('measurement only, not endorsement'), and its limitations ('no auth-bypass, no payment'). This goes far beyond the annotations to disclose scope and 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 extremely long with many clauses and a typo ('SaSame'). While it is front-loaded with the main purpose and uses section-like paragraphs, the level of detail (e.g., the census statistic) makes it less concise than ideal. It is structured but not tightly written, earning a mid-range score.

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?

There is no output schema, so the description must explain return values, and it does: 'It returns the grade, a per-criterion pass/evidence breakdown, and the single biggest gap to fix.' It also covers exclusions, protocol details, and advisory signals, providing a complete picture for a complex tool. Very comprehensive given the absence of structured output 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?

The schema already covers the single parameter (url) with a clear description, so the baseline is 3. The description adds 'Best run against YOUR OWN server,' but this repeats the schema's 'ideally your own.' No additional syntax or format details are provided beyond the schema, so the description does not significantly enrich parameter understanding.

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 opens with a specific verb and resource: 'Grade one MCP server A-D against the Agent-Tool Discoverability Standard.' It clearly distinguishes from sibling tools by stating 'if you want a signed, portable certificate of the same audit, use verify_mcp_ready instead.' This makes the purpose unambiguous and differentiated.

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 the tool: 'DIRECTORY PRE-FLIGHT: ... run it before you submit.' It also states what it does NOT cover ('It does NOT cover privacy-policy, identity/business verification, OAuth callbacks, or prohibited-category rules') and names an alternative tool (verify_mcp_ready). This provides clear usage guidance with exclusions.

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. The description adds value by explaining that an empty log returns 0 with no fabricated activity, and provides context about the nature of recorded statements. No contradiction with 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?

The description is concise at 3-4 sentences with front-loaded purpose. Every sentence provides value, though the caveat statement could be slightly shorter. No redundant information.

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 5 parameters, no output schema, and read-only annotations. The description covers filter options, emptiness behavior, and data limitations, but lacks details on limit behavior and return format, which are necessary for complete understanding.

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 40% (only kind and since have descriptions). The description adds that meter_id, agent_id, kind, and since are filters, but does not explain the limit parameter fully. It provides some additional meaning but does not fully compensate for low schema coverage.

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 verb 'Query' and the resource 'SaSame's append-only audit log', listing specific data types. It is clear but does not explicitly differentiate from sibling tools, though the unique audit log focus makes it distinct.

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 usage context ('Use to reconstruct what SaSame recorded') and includes caveats about party labels and independent proof. However, it does not specify when not to use the tool or mention alternative tools.

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 annotations already declaring readOnlyHint=true, the description adds value by stating it is an 'observation, not a safety verdict', is 'ed25519-signed, offline-verifiable', and is an aggregate that cannot be self-produced. This goes beyond the annotation but could mention data freshness.

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 front-loaded with 'zero-argument ecosystem view' and packs key info, but is a single run-on sentence with minor redundancy. It could be more structured, but it is mostly efficient and informative.

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 no parameters and no output schema, the description covers purpose, content (e.g., capability classes), and security (signed). It lacks response format details, but for an observational tool, it is fairly complete.

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?

With zero parameters, the baseline is 4. The description effectively communicates that no arguments are needed ('zero-argument', 'no URL needed'), fulfilling the requirement without needing further parameter details.

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 is a 'zero-argument ecosystem view' of SaSame's live 'State of the Agent Attack Surface', listing specific metrics (size, capability classes, missing safety annotations). It contrasts with sibling tools like 'capability_profile' which focus on individual tools, making its purpose distinct.

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 it is a 'frictionless first call' and 'cost-zero', suggesting it as an initial query. However, it does not explicitly state when not to use it or name alternatives, though context with siblings like 'capability_profile' provides indirect 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?

The description significantly adds context beyond the readOnlyHint annotation. It details that the tool is cost-zero, operates only on the declared tool surface (from tools/list), flags state-changing tools without machine-readable annotations, provides an exposure tier, and is ed25519-signed and offline-verifiable. It also clarifies it is an observation, not a security claim. No contradiction with 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?

The description is relatively concise for the amount of information conveyed, but it uses all-caps for emphasis (DEFENSIVE, OBSERVATION, NOT) which aids clarity. It front-loads key purpose and usage intent. A minor improvement could be to shorten some run-on sentences, but overall it is well-structured and reasonably sized.

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 what the tool does, how it works (using tools/list, flagging unannotated state-changers, detecting new exposures), and its output characteristics (ed25519-signed, offline-verifiable). However, it does not specify the exact format or structure of the returned profile, which might be expected given the absence of an output schema. Still, it provides a comprehensive high-level overview sufficient for agent understanding.

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 input schema has one parameter 'url' with a description stating 'The MCP server endpoint URL (https) to profile'. The tool description does not add new semantic information about this parameter beyond what the schema already provides. With 100% schema coverage, a baseline of 3 is appropriate, as the description does not elaborate on URL format or validation rules.

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 performs a 'DEFENSIVE pre-call check for one public MCP server' that classifies declared tool surface into capability-risk classes and identifies newly exposed higher-risk classes. It distinguishes itself from siblings by specifying it is an observation of the declared surface, not a vulnerability scan, and differs from tools like 'verify_mcp_cert' or 'audit_mcp'.

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 tells when to use the tool: 'Use it before wiring an untrusted MCP into an agent.' It also clarifies what the tool is not ('NOT a vulnerability/malware scan and NOT a claim the server is unsafe'), providing clear usage boundaries. While it does not explicitly name alternative tools for vulnerability scanning, the context of 'defensive pre-call check' implies its specific use case.

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 mark readOnlyHint=true, so the tool is read-only. The description adds that it returns name, description, and step count, but does not disclose pagination behavior, ordering, or any limits. Since there are no parameters, the behavior is straightforward, but more detail (e.g., 'returns all saved chain recipes') would improve transparency.

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 clear sentence that front-loads the purpose and details. Every word is necessary; there is no redundancy or extra information.

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 simple list tool with no parameters, the description adequately specifies what is returned. However, the lack of an output schema means the agent must infer the exact format. The description could be considered complete given the tool's simplicity, but it is missing potential context like whether the list is paginated or sorted.

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 no parameters, and schema description coverage is 100%, so the baseline is high. The description does not need to add parameter information, and it correctly omits any. A score of 4 reflects that no improvement is needed.

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 verb 'List', the resource 'saved chain recipes', and the fields returned ('name, description, step count'). It is specific and distinguishes the tool from others (e.g., factory_stations lists factory stations, not chain recipes).

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 the tool should be used to view saved chain recipes, but it does not provide explicit guidance on when to use it versus alternatives (e.g., other list tools) or when not to use it. No exclusions or prerequisites are mentioned.

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 explicitly states 'Free, read-only, deterministic — no LLM, no network', which aligns with the annotation readOnlyHint=true. It also describes the return value in detail (conversation thread, state, waiting flag). No contradictions with 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?

The description is concise, consisting of three sentences with no wasted words. The first sentence immediately states the main purpose. It efficiently covers usage, return value, and behavioral traits.

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 (one parameter, read-only). The description adequately explains what is returned, how to use it, and behavioral characteristics. Since there is no output schema, the description covers return types and state enums, making it complete for agent usage.

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% with a single parameter 'ticket' described as 'The engagement ticket returned by engage_sasame'. The description adds only minor reinforcement ('Pass the `ticket` you got back from engage_sasame'), not substantial new meaning. Baseline 3 applies.

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 action: 'Poll the status of an engagement... and READ the human operator's reply'. It specifies the resource ('engagement you opened with engage_sasame') and the verb ('poll'/'read'). This distinguishes it from siblings like 'engage_sasame' (opening) and 'reply_engagement' (sending replies).

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 tells when to use it: after opening an engagement with engage_sasame, passing the ticket. It gives frequency guidance ('call this again periodically, e.g. once a day'). It does not explicitly say when not to use it or alternatives, but the context implies it's for polling only, not for opening or replying.

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 readOnlyHint=true; the description adds that the teaser is public and contrasts with private detailed intelligence. No contradictions. Provides useful behavioral context beyond 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?

One concise sentence front-loading purpose with no wasted words. Highly efficient.

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 tool with annotations covering readOnlyHint, the description fully informs about the public teaser nature and the existence of private detailed intelligence. Complete for its simplicity.

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?

No parameters, so schema coverage is 100%. Baseline 4 for 0 params applies; description does not need to add parameter info.

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 a public teaser of the MCP Gold Rush Chronicle, distinguishing it from a paid private version. The verb 'Return' and resource are specific, and it differentiates from sibling tools like gold_rush_report.

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 use for a public teaser only, noting detailed intelligence is private/paid. This provides clear context, but does not explicitly list alternative tools for detailed info.

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 claims creation of a durable receipt on each match, which contradicts the idempotentHint=true annotation implying repeated calls have same effect. It does disclose SSRF-guarded and free, but the inconsistency reduces transparency.

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 informative but slightly verbose. It front-loads the core action and includes useful details like the readiness certificate and SSRF protection, though a bit more conciseness would improve it.

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 no output schema and one parameter, the description is highly complete: it explains the process, conditions, outcome (receipt, claimed marker), and separation of readiness badge. No gaps remain.

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 the description adds context: the URL must be HTTPS and identical to claim_start. It also explains the verification mechanism, adding value beyond the schema.

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: confirming domain control proof to upgrade listing from Observed to CLAIMED. It uses specific verbs (confirm, upgrade) and resource (domain listing status), and distinguishes from sibling tools like claim_start and town_claim_confirm.

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 explains when to use (after claim_start, verifying a challenge token) and the process (checking well-known file or DNS TXT). It doesn't explicitly state when not to use or name alternatives, but the context is sufficient.

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?

Beyond annotations indicating idempotent, non-destructive, non-read-only, the description adds significant context: returns a challenge token, two verification methods, receipt and marker upon verification, and conditions for readiness badge. No contradictions with 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?

The description is information-dense but structured: purpose, method, outcomes. A bit long but each sentence adds value. Could be slightly more concise.

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?

Covers purpose, input, multi-step process, and results. No output schema, but describes return of challenge token. Missing error cases, but adequate for initiating a multi-step flow.

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?

Input schema has 100% coverage with a description for the single required parameter 'url'. The description does not add new meaning beyond the schema, so baseline 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 the verb 'Start claiming' and the resource 'YOUR MCP server'. It also distinguishes from sibling tools like claim_confirm and town_claim_start by describing the initiating step of the claim process.

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 explains when to use this tool (to start claiming) and outlines the subsequent steps (serve token or DNS record, then call claim_confirm). It implicitly suggests not to use if already claimed, but lacks explicit 'when not to use' or alternative tools.

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 declare readOnlyHint=true, so the description's emphasis on 'honest aggregate' and 'no fabrication' adds context about truthfulness of empty results. It explains the data source and that empty means empty, which are behavioral traits beyond 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?

The description is fairly concise and front-loaded with the core purpose. It contains no unnecessary words, though it could be slightly shorter by removing redundant emphasis on honesty. Still efficient.

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 no parameters and no output schema, the description explains the output fields (top need phrases, counts, percentages, total sessions, time window) sufficiently. It does not mention sorting or pagination, but for a read-only aggregate, it is complete enough.

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 baseline is 4. The description correctly omits parameter details as none exist.

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 that the tool aggregates what agents have asked for via register_intent and passive logging. It specifies verb 'aggregate' and resource 'demand/needs', and lists output fields (top need phrases, counts, percentages). It implicitly distinguishes from sibling register_intent (which registers) and other analytics 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 usage for checking demand for agent requests, but does not explicitly state when to use this tool versus alternative analytics tools like analytics_next_steps or capability_landscape. No when-not or alternative guidance is provided.

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 provide readOnlyHint and openWorldHint. Description adds that the tool is free, searches a live catalog with size varying by source, and returns price, quality score, category, and URL. No mention of rate limits or pagination, but adds significant behavioral context.

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?

Three sentences, front-loaded with purpose and scope, no wasted words. Efficiently conveys purpose, outputs, and use case.

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?

Describes output fields and free nature. Lacks details on result limits, sorting, or caching, but sufficient for a simple search tool with one parameter.

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 covers the only parameter (query) with a description. Description restates that it searches for services relevant to the query, adding little beyond the schema.

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?

Description clearly states it searches the x402 agent-economy catalog for services relevant to a query, returning ranked matches. Distinguishes from siblings like recommend_mcp and capability_landscape by specifying it's a search over a live catalog.

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?

Explicitly states usefulness for discovering agents/APIs to delegate to, providing clear context. Does not mention when not to use or explicitly name alternatives, but the use case is well-defined.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds key behavioral context: it's free, creates a ticket, continues over MCP with check_engagement/reply_engagement, and warns against posting secrets.

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 about 100 words, front-loaded with the core purpose, and every sentence adds value without repetition 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?

Despite no output schema, the description explains the outcome (creating a ticket and continuing via check_engagement/reply_engagement). It covers all necessary context for an engagement submission tool.

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% with all five parameters documented. The description adds context about the 'ref' parameter being from the 'refer' tool, but does not further elaborate on parameter details beyond the schema.

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 opens an 'evidence-backed External Call Activation engagement' for a public MCP. It distinguishes itself from sibling tools like audit_mcp and check_engagement/reply_engagement by specifying when to use it.

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 'Use this after or alongside audit_mcp' and provides clear context for when to engage. It also notes that it's free to submit with no contract created, setting expectations for usage.

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 provide no behavioral cues; the description compensates fully by detailing that SaSame signs a portable authorization, holds/moves nothing, and that the tool is terminal (double-release refused). No contradiction with 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?

The description is efficient (5 sentences) and front-loaded with main verb and resource. Minor redundancy ('SaSame' repeated, 'once the outcome is reported/verified' implied elsewhere) could be tightened, but no extraneous content.

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 4 parameters, no output schema, and minimal annotations, the description covers purpose, outcome options, evidence guidance, and terminality. It mentions the signed data structure but lacks explicit return format. Could briefly describe the output for full 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?

Schema coverage is 100% with clear descriptions. The description adds value by explaining that escrow_id comes from escrow_open and gives examples for evidence, though it introduces 'amount' and 'ts' not in input schema, causing slight confusion. Overall well-supported.

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 verb 'Sign' and the resource 'release OR refund authorization for an open escrow', distinguishing it from sibling tools like escrow_open and escrow_status by specifying it operates on open escrows after outcome verification.

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?

Explicitly states when to use (after outcome reported/verified), notes terminal behavior (cannot re-attest after settlement), and provides alternative guidance for objective vs subjective conditions by referencing audit_mcp.

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 adds significant behavioral context beyond annotations: it states SaSame holds no funds, moves no money, records in an append-only ledger, signs envelopes, and requires external settlement venue configuration. This gives the agent critical safety and dependency information.

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, front-loaded with the main purpose, and every sentence adds value. No wasted words; it efficiently communicates the tool's essence and key behaviors.

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?

While behavioral context is rich, the description lacks any mention of return values or output. Since there is no output schema, the agent is left guessing what the tool returns (e.g., a signature or escrow ID). This is a notable gap for a creation tool.

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% with good parameter descriptions. The tool description adds system-level context that explains the role of parameters, e.g., amount is informational and settlement_ref is where funds sit, enhancing understanding beyond the schema.

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 opens a non-custodial conditional-release escrow, specifying the verb 'open' and the resource 'escrow'. It distinguishes from siblings like escrow_attest and escrow_status by emphasizing the creation action and the non-custodial nature.

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 explains when to use (to create a non-custodial escrow) and provides context on how it works, but does not explicitly exclude other tools or mention alternatives like escrow_attest for attestation.

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, so the agent knows it's read-only. The description adds valuable context: the returned statement is ed25519-signed, offline-verifiable with trust_pubkey, and attestations carry signed authorization. This reveals behavioral traits beyond the annotation.

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, each packed with relevant information. No wasted words. The first sentence states the purpose and key contents; the second adds verifiability details. Efficient and 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 simplicity (1 param, no output schema, clear annotations), the description covers what is returned, security properties, and relationship to the broader escrow system. It feels complete without requiring additional clarification.

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 baseline is 3. The description does not add extra meaning for the escrow_id parameter beyond the schema's 'The escrow_id from escrow_open.' No format, validation, or derivation rules are provided.

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 an escrow's current state and lists specific elements (terms, release condition, settlement status, signed attestations). It distinguishes itself from sibling tools like escrow_open (creation) and escrow_attest (modification).

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 implicitly indicates this tool is for reading state, not for mutating escrows, but it does not explicitly state when to use or exclude alternatives. The sibling context suggests alternatives exist, but no direct guidance is given.

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, idempotentHint, destructiveHint. Description adds that it never creates or charges, reinforcing but not adding beyond annotations. No 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?

Four concise sentences, each adding meaningful context. Front-loaded with main action. No 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 zero required params, no output schema, and simple read-only nature, description adequately covers legacy context and relationship to 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?

Schema coverage is 100%, but parameters are deprecated and ignored. Description explains the tool never charges, which gives context for why parameters are ignored, but doesn't add significant value over schema descriptions.

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?

Description clearly states it reads retirement status of a legacy checkout rail. Distinguishes from sibling factory_membership_checkout by naming it as the current paid access tool.

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?

Explicitly says when to use (read retirement status of legacy Activation checkout) and when not (new sales closed, use factory_membership_checkout for current access).

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. The description adds that it contains no customer data or secrets, and lists specific data items, providing useful behavioral context beyond 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?

Single sentence, no wasted words. Front-loads key action 'Read the Factory conveyor health...'.

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 simple health-check tool with no parameters and no output schema, the description fully conveys what it does and what data it returns.

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?

No parameters, baseline 4. Description adds meaning by specifying what data is returned, compensating for lack of output schema.

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 reads conveyor health, persistence sequence, and Stripe mode. It is specific about the resource, but does not differentiate from sibling tools like factory_status.

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?

No guidance on when to use this tool vs alternatives. Does not indicate prerequisites or exclusions.

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?

Beyond annotations (readOnly, idempotent hints), description discloses real-money charge via Stripe LIVE mode, principal_id binding semantics (buyer email never binds), and the unavailability of assisted_review due to no fulfillment path. These are meaningful behavioral traits not present in 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?

Four sentences, each adds value: purpose, plans, binding/exclusions, and payment warning. No redundant repetition of schema or annotation fields; front-loaded with action.

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 complex checkout tool with 8 params and no output schema, description covers purpose, plans, binding rules, exclusions, and live-payment warning. It doesn't mention return shape or prerequisite that principal must be registered, but annotations and schema fill many gaps. It's largely complete but not exhaustive.

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 already covers 75% of parameters with descriptions, so baseline is 3. Description adds meaningful semantics for principal_id (binding by principal_id, not email) and for stripe_live_payment_acknowledged (charges real money), and lists the valid plan values for plan_id. This extra context justifies 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?

Description uses specific verb 'Create' plus resource 'account-level Factory membership Stripe LIVE subscription Checkout' and explicitly lists plans. It also distinguishes itself by stating what it does NOT sell (assisted_review) and that free_listing needs no checkout, so an agent can tell it apart from sibling tools like factory_checkout.

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?

States clear context: account-level membership checkout for a principal, with plan options. Gives explicit when-not-to-use: assisted_review is NOT sold here and free_listing needs no checkout. However it doesn't explicitly name an alternative tool for assisted_review, so it stops short of full alternative 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, and the description adds valuable behavioral context: 'Losing paid access only removes paid capabilities; no lifecycle, claim or receipt history is ever deleted.' This clarifies data persistence and mutation effects beyond what annotations provide. The description also details what the read returns, enhancing transparency.

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 front-loaded with the core purpose and data, followed by parameter requirements and a behavioral note. At three sentences, it is concise and avoids redundancy. Minor improvement could be possible by tightening the parameter sentence, but overall it is well-structured.

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 read-only tool without an output schema, the description adequately lists the returned fields and adds behavioral context. It is missing explanations of terms like 'principal' or 'Factory', and does not hint at error conditions or response structure, but given the tool's simplicity, the coverage is sufficient for most use cases.

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?

With 0% schema description coverage, the description should compensate by explaining the parameters. It merely states 'Requires the principal_id and its principal_key' without adding meaning beyond their names. No format, examples, or purpose are given, leaving the agent underinformed about what values to provide.

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 uses a specific verb 'Read' and clearly identifies the resource as 'one principal's account-level Factory membership'. It lists the exact data returned (subscription status, plan, period end, plan capabilities, slot usage), which distinguishes it from sibling tools like factory_status or factory_health that serve different purposes.

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 states the required parameters (principal_id and principal_key) but does not explicitly tell when to use this tool versus alternatives. It implies usage for reading membership details, but no when-not-to-use or alternative tool suggestions are provided, leaving the agent to infer context from the tool's name and purpose.

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 a write operation (readOnlyHint false). Description adds valuable context: the principal_key is shown once and unrecoverable, contact_email is stored hash-only and not used for authority. No contradictions.

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 compact: two sentences plus a clause. Front-loaded with purpose and key behavioral notes. Every sentence earns its place with no 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?

No output schema, but description explains return values and critical warning about key recovery. Covers the essential behavioral aspects. Could mention error cases or rate limits, but sufficient for a registration tool.

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 baseline 3. Description adds meaning for contact_email by repeating its optional nature and security properties, going beyond the schema's description. display_ref and analytics_correlation_id receive no extra explanation, but the added value for contact_email justifies a 4.

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 registers a durable, free SaSame Factory principal. It specifies the return values (principal_id, principal_key) and highlights the key's single-show nature. Differentiates from siblings like factory_checkout by mentioning 'no checkout, no charge' and owning a portfolio.

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?

Explicitly says no checkout or charge, implying when to use this over checkout-related tools. Provides context for the principal's capabilities but does not explicitly mention alternatives like register_intent or when not to use.

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?

Adds detailed behavioral context beyond annotations: describes effect on open_dead_letter_count vs dead_letter_count, security implications, and token requirements. Annotations are minimal, so description carries the burden excellently.

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?

Front-loaded with purpose and ownership. Every sentence adds value, no fluff. Length is justified by the complexity of the tool.

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?

Covers ownership, token, classification, and count effects. Lacks description of return value/response, but as a mutation tool without output schema, this is a minor gap.

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 covers all 4 parameters with descriptions. The description adds minor extra context (e.g., token being 'Release-bound, single-use, short-lived'), but overall adds little beyond what the schema already provides.

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 classifies and closes a webhook dead-letter entry into two categories. It uses specific verbs and resource, but does not distinguish from sibling tools directly.

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?

Provides explicit ownership requirement, token minting instructions, and security rationale. Does not list alternative tools but gives clear context for when to use.

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 discloses that no checkout is created and redirect never grants access, which aligns with the annotations (destructiveHint=false, readOnlyHint=false). It explains behavioral traits like membership requirements, endpoint optionality for guided builds, and special handling for self_test. This adds value beyond 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?

The description is packed with information in three long sentences, which is informative but somewhat dense. It is front-loaded with the main purpose, but the length could be reduced without losing clarity. A more structured approach (e.g., bullet points) would improve readability.

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 14 parameters with full schema coverage, the description covers most behavioral aspects: entry types, membership requirements, endpoint timing, and self_test restrictions. However, it does not describe what the tool returns (e.g., a journey ID or status), which would be helpful since no output schema exists. Still, it is largely complete for a starter tool.

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 input schema already provides descriptions for all 14 parameters (100% coverage). The description adds meaning by grouping entry types, explaining the alias relationship between entry_type and journey_id, and clarifying when endpoint is required vs optional. This provides context beyond the schema.

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 starts the SaSame MCP Factory lifecycle from seven canonical entry types. It distinguishes each entry type's purpose (free listing vs. paid guided-build vs. monitoring vs. underperforming), and mentions a related sibling tool (factory_provide_endpoint). This is specific and avoids tautology.

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 states when to use each entry type, what is required (e.g., membership for paid journeys, endpoint for live_entry), and when not to use (e.g., self_test_free_distribution is SaSame-internal only). It provides clear context but does not directly compare to other sibling tools beyond mentioning factory_provide_endpoint.

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. The description adds value by explicitly stating the tool 'never advances or fabricates completion', providing behavioral clarity beyond the annotations. No 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?

Two sentences, no unnecessary words. Front-loaded with the core purpose, followed by a critical usage note. Every sentence adds value.

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 adequately covers the tool's purpose and key behavior given the annotations and parameter count. Lack of output schema is mitigated by the clear read-only intention, but a brief note on the return format would enhance 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?

Schema description coverage is low (33%). The description does not elaborate on lifecycle_id or station_id beyond the schema, though it mentions the lifecycle key requirement. This provides some context but does not fully compensate for the missing parameter descriptions.

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 action ('Read') and the resource ('canonical station's private status and allowed operations') with specific context ('Factory lifecycle'). It distinguishes from sibling tools like factory_stations and factory_station_action by focusing on a single station's private read-only state.

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 states the requirement for an unguessable lifecycle key, indicating when this tool is appropriate. It implies not to use when needing to advance or fabricate completion, but does not explicitly name alternative tools or provide 'when not to use' guidance, keeping it at 4.

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 discloses important behavioral traits beyond annotations: 'The runtime authorizes the operation from lifecycle state and evidence, rejects station skipping, and never treats a request as verified completion' and 'Creator code and credentials remain creator-owned.' This adds context about authorization, non-verification, and ownership, complementing the annotations without 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 two sentences, front-loaded with the purpose, and contains no superfluous text. Every sentence adds value, making it concise and well-structured.

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 complexity (5 parameters, no output schema), the description covers authorization, rejection, non-verification, and ownership. It lacks details on success/failure responses or side effects, but the main behavioral aspects are addressed, making it fairly complete.

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 40%, and the tool description does not explain individual parameter meanings (e.g., lifecycle_id, lifecycle_key, action enum values). While it vaguely references lifecycle state, it fails to compensate for the low coverage, leaving agents unclear on parameter specifics.

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 'Request one operation at one canonical Factory station,' specifying a verb (Request), resource (operation at Factory station), and scope (one station, one operation). It also mentions authorization and rejection of skipping, making the purpose unambiguous and distinguishable from siblings.

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 clear context for when to use the tool (e.g., runtime authorization from lifecycle state and evidence, rejects station skipping). However, it does not explicitly mention when not to use or compare to sibling tools, but the behavioral details are sufficient for typical use.

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 provide readOnlyHint=true and openWorldHint=false. The description adds value by specifying what data is returned (maturity, recovery controls, operations) and clarifying it's metadata, not a quality/launch verdict. No contradiction with 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?

Two sentences, front-loaded with the core action. No redundant words. Efficient and to the point.

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 explains the purpose and content (maturity, recovery controls, operations) but lacks details on output format. However, for a zero-parameter, no-output-schema tool, it provides sufficient context for selection and use.

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 has zero parameters and 100% coverage, so baseline is 4. Description adds no parameter info, but none is needed. It does not repeat schema details, which 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 explicitly states it lists the canonical 21 SaSame Factory stations with specific attributes (maturity, recovery controls, operations). It clearly distinguishes from siblings like 'factory_station' (singular) and 'factory_station_action', and clarifies it is metadata, not a quality verdict.

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 to use (for listing all stations) but does not explicitly mention alternatives like 'factory_station' for single-station details. It provides context that it's capability/status metadata, which aids in understanding appropriate use.

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, so the description's 'Read' operation aligns. The description adds value by detailing the scope (all 21 stations, receipts, billing) and the key requirement, which goes beyond annotation signals. No contradictions.

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 with no redundancy. The first sentence enumerates the read scope; the second specifies the key requirement. Every word adds value.

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 complexity (many state components) and absence of output schema, the description provides a useful summary of returned data. It omits error scenarios (e.g., invalid key) but overall gives sufficient context for an agent to understand what to expect.

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 0%, so the description must explain both parameters. It mentions 'lifecycle key' but not lifecycle_id, leaving the agent to infer that lifecycle_id identifies the lifecycle. This is insufficient for an agent to correctly supply the required inputs without additional knowledge.

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 verb 'Read' and the resource 'one Factory lifecycle', listing specific data elements (21 station states, receipts, billing/entitlement, blocking reason). This distinguishes it from sibling tools like factory_start (which creates) or factory_health (which checks health), providing unambiguous purpose.

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 requires the 'unguessable lifecycle key returned once by factory_start', indicating this tool is used after starting a factory lifecycle. It does not list exclusions or alternatives, but the context makes it clear that other status tools (e.g., factory_health) exist for different purposes.

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 readOnlyHint annotation by explaining the cryptographic mechanism, detection of altered or forged receipts, and the trusted key relationship. No contradictions with 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?

Two concise sentences that front-load the purpose and include essential details without redundancy. Every sentence adds meaning.

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?

Despite the lack of an output schema, the description covers purpose, input sourcing, and detection capability. It could be slightly more explicit about the return value format (e.g., boolean), but overall it is adequate for a single-parameter verification tool.

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% with a good description of the receipt object. The tool description adds value by citing specific source tools (factory_status, factory_start) for obtaining the receipt, which aids agent understanding.

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 uses a specific verb-resource pair ('Offline-verify a Factory lifecycle station receipt's ed25519 signature') and distinguishes itself from siblings like verify_mcp_cert by specifying the same key usage and different target (receipt vs cert).

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 clearly says to pass a receipt object exactly as returned by factory_status/factory_start/etc, providing practical sourcing. However, it does not explicitly state when not to use this tool or suggest alternatives.

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 declare readOnlyHint=true, and the description reinforces that it is 'free, read-only, no signup.' It also discloses that the badge 'is a re-checkable measurement, not an endorsement' and changes as the grade moves, providing full behavioral transparency.

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 packed with useful information in a few sentences, though slightly verbose. It front-loads the main purpose and returns, making it easy to scan.

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?

Despite no output schema, the description fully explains the return value (markdown+HTML snippet, certificate URL) and error handling (server not observed case). For a single-parameter tool with read-only behavior, this is complete.

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% for the single 'url' parameter. The description adds minimal extra context ('ideally your own'), which is useful but not substantial. Baseline 3 is appropriate as the schema already defines the parameter adequately.

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 uses specific language: 'Get your embeddable 'SaSame MCP Readiness' status badge' and explains what it renders, distinguishing it from sibling tools like get_mark_snippet or get_usage_badge by focusing on the readiness badge with a public standard.

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 states when to use (to get a badge for a server), what to do if the server isn't observed ('run audit_mcp(url) first'), and how to make it owner-confirmed ('claim_start'). It lacks explicit exclusions but provides clear context.

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 indicate readOnlyHint=true. The description adds that this returns a status mark, not an endorsement, but does not disclose other behavioral traits such as error handling, caching, or impact of invalid URLs.

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 with no redundancy. The first sentence efficiently conveys purpose and output types; the second provides a clarifying caveat.

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?

Lists the snippet types, but lacks description of the return format or structure (no output schema). Also does not differentiate from the similar sibling 'get_mcp_mark_snippet', which could confuse selection.

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 both parameters are documented in the schema. The description does not add additional meaning beyond the schema's field descriptions.

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 copy/paste snippets for turning SaSame observations into visible status badges and fragments. It lists specific snippet types (README badge, HTML badge, etc.), but does not explicitly differentiate from siblings like 'get_badge' or 'get_mcp_mark_snippet'.

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?

No guidance on when to use this tool versus alternatives. Siblings include similar tools like 'get_badge' and 'get_mcp_mark_snippet', but the description does not explain why one would choose this tool over those.

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 indicate idempotentHint=true (safe to retry) and destructiveHint=false. The description adds no new behavioral context, such as authentication requirements or side effects, but does not contradict 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?

The description is a single sentence with no unnecessary words. It is concise and front-loaded with the key verb and resource, but lacks structure (e.g., not breaking down use cases or assumptions).

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?

With no output schema, the description should explain return format or structure. It lists snippet types but does not indicate whether the result is a JSON object, a string, or a file. This is insufficient for an agent to reliably use the tool's output.

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 0%, meaning no parameters have descriptions. The tool description does not mention or explain the parameters `url` (required) or `name` (optional), leaving the agent without any guidance on their meaning or format.

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 verb 'Return' and the resource 'snippets for the signed SaSame Record Mark.' It includes specific snippet types (README, HTML, etc.) and distinguishes from the sibling `get_mark_snippet` by mentioning 'signed SaSame Record Mark,' though the differentiation is implicit.

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?

No guidance is provided on when to use this tool versus alternatives. The sibling `get_mark_snippet` exists but is not mentioned, and there is no indication of prerequisites or context for choosing this tool.

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, and the description reinforces that calling never charges. It also notes that the tool reports without redefining exact prices, adding behavioral context beyond the annotation.

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 that are front-loaded with the core purpose, followed by a clear note on side effects. No unnecessary 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?

With no output schema, the description partially explains the return value (capacity, SKU references, fulfillment paths) but does not specify the structure, format, or how these elements are presented, which may leave the agent uncertain about what to expect.

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 description bears no burden for parameter explanation. The schema coverage is 100% (empty schema), and the description does not need to add parameter details.

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 returns a commercial projection for a single product, listing specific elements like capacity, SKU references, and fulfillment paths. However, it does not explicitly distinguish itself from the sibling 'pricing_overview' tool, which may have overlapping functionality.

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 no guidance on when to use this tool versus alternatives. The only usage hint is 'Calling this tool never charges,' which is more about side effects than use cases.

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; the description adds context about the standard's content and philosophy. It does not contradict annotations but also does not fully describe behavioral traits like return format or side effects.

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 front-loaded with the key action and provides additional context in a few sentences. It is efficient but slightly verbose in explaining the standard's philosophy.

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?

With no output schema, the description should clarify the return type or format. It covers the tool's purpose well but lacks specifics on how the result is delivered (e.g., JSON string, markdown).

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?

No parameters exist, and the schema covers them fully (100%). Baseline score of 4 applies since the description adds nothing about parameters, which 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 returns the Agent-Tool Discoverability Standard v0.3 and explains its purpose. It distinguishes itself from siblings like lookup_readiness by focusing on the criteria document itself, though it does not explicitly call out 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?

No guidance on when to use this tool versus alternatives such as lookup_readiness or verify_mcp_ready. The description explains what the tool does but not the decision context for invoking it.

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 idempotent, non-destructive, and not read-only. The description adds that it can create an 'Observed mark' if needed, which is a useful behavioral trait beyond annotations. However, no details on response format or error handling.

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?

Single sentence, but includes a typo ('SaSame') and is somewhat ambiguous. Could be more structured with separate clauses for primary action and side effect.

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?

With two undocumented parameters, no output schema, and related sibling tools, the description lacks sufficient context for correct invocation. Missing details on parameter usage and differentiation.

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 0%, and the description does not explain what the 'url' or 'name' parameters represent. The agent must guess their purpose, which is a significant gap.

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 badge URLs/embed code, with a specific resource ('SaSame Record Mark'). It also mentions a side effect (creating mark if needed), which adds clarity. However, the typo 'SaSame' may cause slight confusion.

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?

No guidance on when to use this tool versus alternatives like get_badge or usage_mark_issue. No context on prerequisites or exclusions.

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 adds significant behavioral context beyond annotations: it writes an append-only action event, returns the next safe step, and explicitly lists what steps are allowed and what effects are never triggered. This complements annotations (readOnlyHint false, openWorldHint true) without 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 (4 sentences) and front-loaded with the core purpose. Every sentence adds value without redundancy, achieving a high information-to-word ratio.

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 one simple parameter, no output schema, and a straightforward action, the description covers the essential: it writes an append-only event and returns the next safe step. It could be slightly more complete by hinting at the response format, but overall it suffices given the low complexity.

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 0%, so the description should explain parameters. The only parameter 'package_id' is not described, leaving the agent to infer its meaning from context. While the parameter name is self-explanatory, the description misses an opportunity to clarify its role (e.g., the package to advance).

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 advances a Gold Rush Agent Package by one deterministic step, listing specific step types (observe → claim_instructions/report → receipt). It also explicitly distinguishes itself from tools that trigger live settlement, DNS, etc., making its scope 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?

The description indicates when to use the tool (advancing a package under standing authorization) and what it does not do (never triggers external actions). However, it does not mention specific alternatives among sibling tools like gold_rush_package_status or gold_rush_start, leaving some ambiguity.

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. The description adds context: append-only, returns factual data, public-safe, and lists fields. No contradictions.

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?

Three concise sentences front-load the action and key details, with no unnecessary 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?

For a simple read tool with one parameter and no output schema, the description covers purpose, returns, safety, and read-only nature. Could mention pagination limits but overall sufficient.

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 has one string parameter with 0% coverage. The description says 'by package_id' implying the parameter, but lacks details on format or constraints. Adequate for a single obvious param.

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 append-only state of a Gold Rush Agent Package by package_id, listing specific return fields. It distinguishes from sibling gold_rush tools (agent_run, report, start) by focusing on package status.

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 mentions 'Public_safe only' and 'Measurement only,' implying safe use for queries, but does not explicitly state when to use or not use this tool versus alternatives, nor provide 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 mark the tool as readOnlyHint=true and openWorldHint=true. The description adds behavioral context: it lists what the report includes (e.g., runtime health, tool-surface readability) and what it avoids (endorsement, safety guarantees), and notes 'Public_safe' for safety. This supplements the annotations well.

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, front-loading the main action and then detailing content and limitations. It is concise without being cryptic, though it could be slightly more structured.

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 no output schema, the description explains the output format and contents adequately. However, it fails to clarify the 'format' parameter and does not specify required vs optional parameters, leaving gaps for the 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?

The input schema has 0% description coverage for parameters, and the description does not explain the 'format' parameter or provide details beyond the obvious 'package_id'. The description mentions 'JSON + Markdown' but does not link it to the format parameter. This leaves the agent unclear on parameter usage.

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: 'Produce the Gold Rush Visibility Report for a package (JSON + Markdown).' It also lists specific contents (runtime health, tool-surface readability, etc.), making it distinct from sibling tools like gold_rush_agent_run or gold_rush_package_status.

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 does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention contexts where it should not be used. Usage is implied but not clarified.

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?

Beyond idempotentHint, description reveals that the tool creates or identifies an append-only record, returns specific fields, and never triggers payment, DNS, wallet, etc. This adds value beyond 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?

Well-structured with front-loaded purpose and bolded emphasis. However, a few sentences could be trimmed without losing clarity.

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 starting tool with no output schema, the description lists all returned fields (package_id, mcp_id, preset, etc.) and clarifies constraints (no payment, no contact required). Adequate for decision-making.

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 0%, so description must compensate. Only 'Optional mcp_url + goal' is mentioned, but 'contact' parameter is ignored. No details on parameter types or expected values.

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?

Description clearly states the tool starts the Gold Rush Agent Package, a guided journey over multiple systems. It specifies what it creates/identifies and returns. Despite not explicitly differentiating from siblings, the purpose is specific and actionable.

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?

Description provides clear context: it's a measurement-only tool, no payment or live settlement, and no contact data required. It implies when to use (starting a guided journey) but does not explicitly mention alternatives or when not to use.

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. The description adds context that hints are 'broad public' and limited compared to paid/private, which is useful behavioral info beyond the annotation.

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 concise sentences, front-loaded with purpose, no unnecessary 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 no output schema and zero parameters, the description is brief. It does not explain what 'hints' consist of, but the simplicity of the tool makes this acceptable. Could be improved by describing the output format.

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?

No parameters in input schema; baseline score for 0 parameters is 4. The description does not need to add parameter details as there are none.

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 verb 'Return' and resource 'broad public Gold Vein hints', and distinguishes from specific paid/private opportunities. However, it does not explicitly name a sibling tool for the paid version.

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 to use this tool (for broad public hints) and hints at alternative (paid/private for specific opportunities), but lacks explicit when-not-to-use or named alternatives.

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 mark readOnlyHint=true, so the agent knows it's safe. The description adds that it returns verified/unverified markers, filters ghost agents, and is free, providing useful behavioral context beyond 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?

Concise, front-loaded with purpose, then details, then usage guidance. Every sentence adds value.

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 no parameters and no output schema, the description adequately describes the output content and purpose. Could mention format (machine-readable, open standards) but overall complete.

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?

No parameters in schema, baseline score 4. Description does not need to add parameter info.

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 reads the Gold Rush Guild feed, specifies the output (participant roster with content_verified markers, filtering ghost agents, plus recent posts), and distinguishes from sibling join_guild.

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?

Explicitly states 'Use to discover other agents and SaSame's latest activity' and directs users who want to appear in the feed to use join_guild 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?

The description adds significant transparency beyond annotations: it discloses human moderation, content-verification via SaSame Audit, self-claimed identity, and that the service is free. Annotations already indicate idempotent and non-destructive, and the description is consistent with these.

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 four sentences, front-loaded with the core purpose, and every sentence adds value without redundancy. It is concise yet informative.

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 4 parameters and no output schema, the description covers the submission lifecycle, moderation, verification outcomes, and positioning. It lacks explicit details on what the response contains, but given no output schema, this is acceptable.

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% with clear descriptions for each parameter. The description adds natural-language context (e.g., 'submit a short Note' for content, 'live endpoint/agent-card URL' for url) that reinforces understanding, though the schema already covers basics.

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 verb 'Join' and the resource 'Gold Rush Guild', and explains the purpose of broadcasting to SaSame's open agent feed. It distinguishes from siblings like gold_rush_agent_run and town_become_citizen by focusing on discoverability via the guild feed.

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 good context on when to use the tool ('a low-threshold way to gain discoverability') and explains the process (submit note, human moderation, publication). However, it does not explicitly mention when not to use it or suggest alternative tools among the siblings.

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; the description adds that it is a measurement record only, reinforcing the read-only nature and clarifying it is not a security audit. However, no additional behavioral details (e.g., rate limits, data freshness) are provided.

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 extremely concise, with only two sentences. The main action is front-loaded ('Look up the public Gold Rush Passport'), and the second sentence adds essential context without 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?

There is no output schema, and the description does not describe the return value beyond calling it a 'measurement record'. The agent has no idea what fields or structure to expect, which is a significant gap for a lookup tool.

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 0%, but the description indicates that the parameters are for an 'MCP URL or mcp_id', implying one of them is used. However, it does not specify format, constraints, or whether both can be provided, leaving ambiguity.

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 verb ('Look up'), resource ('public Gold Rush Passport'), and scope ('for an MCP URL or mcp_id'). It also clarifies it is for measurement, not security, which distinguishes it from sibling tools like provenance_verify_passport.

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 some usage context ('Measurement record only, not a security audit') but does not explicitly state when to use this tool versus alternatives or what prerequisites exist. There is no mention of when not to use it.

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 indicate readOnlyHint=true. The description adds substantial behavioral context: it is a pure read with no live probe, no network activity, instant. It explains the source (SaSame's observation ledger with stats like 25,000+ endpoints, 88,000+ measurements), and that the attestation can be verified offline. No contradiction with 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?

The description is somewhat long but well-structured, front-loading the main purpose. Every sentence adds value (purpose, read-only, verification, source, alternative action). Could be slightly more concise without losing information, but overall efficient.

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 one parameter and no output schema, the description provides rich context: what is returned (freshly signed attestation for offline verification), the source (SaSame's ledger with stats), and what to do if not found. It addresses the user's likely needs fully.

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% with a single parameter 'url'. The description mentions 'MCP/agent endpoint URL or domain' which is already covered by the schema description. The description adds no new meaning beyond the schema, so baseline 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 the tool's purpose: look up SaSame's existing signed readiness attestation for any MCP/agent endpoint. It specifies it is a pure read operation with no live probe, distinguishing it from other tools like audit_mcp which adds new records. The scope (existing records) and constraints (no network instant) are explicit.

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 states when to use: to look up an existing attestation. It clarifies what the result is NOT (a safety/quality/trust verdict). It provides an alternative action if the endpoint is not yet observed: call audit_mcp. This gives clear guidance on usage versus alternatives.

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 include readOnlyHint=true, and the description reinforces this by saying 'Public-safe latest status only'. It adds context beyond annotations by stating 'not an endorsement'. No 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?

Two concise sentences, no filler. Each sentence adds value: first states action and resource, second adds qualifiers.

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?

Tool has no output schema and few parameters. The description covers purpose and behavioral limits but does not describe the return value or structure of the registry entry. While adequate for a simple lookup, more detail on output 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?

Parameter names (url, mcp_id) are self-explanatory, and the description mentions 'MCP URL or mcp_id' implying they are alternative identifiers. However, with 0% schema description coverage, the description could have explained each parameter's format or constraints more thoroughly.

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: to look up a public MCP Registry entry using either a URL or mcp_id. It specifies the resource and action, distinguishing it from sibling tools like lookup_passport or lookup_readiness.

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 when to use ('public-safe latest status') and what it is not ('not an endorsement'). While it does not explicitly list alternatives or when not to use, the context is adequate for an agent to decide.

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, so the read-only nature is clear. The description adds that it is 'not a recommendation,' which is relevant behavioral context. However, it does not disclose other traits like data freshness, caching, or what 'public aggregate' means in terms of data scope.

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 with a brief clarifying clause. Every word is necessary and no extraneous information is included. It is appropriately front-loaded with the core action and resource.

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 read-only tool with no parameters and no output schema, the description provides the essential purpose and a key limitation (not a recommendation). However, it does not describe the output format or typical usage context, which would help an agent understand the expected return value for 'Market Context'.

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 and schema coverage is 100% (vacuously). The description's mention of 'public aggregate' aligns with the absence of parameters, implying no user-specific filtering. Baseline for zero parameters is 4, and the description does not contradict this.

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 action (Return) and the resource (public aggregate MCP Market Context). It adds a clarifying statement that it is not a recommendation, which helps distinguish from some similar tools, but could be more specific about what 'Market Context' includes.

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 usage for aggregate measurements rather than recommendations via the statement 'Aggregate measurement context only; not a recommendation.' However, it does not explicitly name alternative tools for recommendations or other use cases, leaving the agent to infer from sibling tool names.

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 discloses that charges are capped and rejected if exceeding budget, and returns a signed denial. Annotations provide readOnlyHint=false and destructiveHint=false, and the description adds important context: budget enforcement is coded outside the model, which is critical for an autonomous agent. No contradiction with 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?

Two sentences that efficiently convey purpose, behavior, and return value. Front-loaded with the primary action ('Record a charge against a meter and ENFORCE the cap'), no redundant 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 has no output schema, the description explains the return format (remaining + signed line-item). The core behavior (cap enforcement, rejection on excess) is fully covered. For a mutation tool with 3 parameters, this is complete and actionable for an AI 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% with descriptions for all three parameters. The description reiterates 'meter_id from meter_open' which adds slight context beyond the schema, but does not significantly enhance parameter understanding. Baseline 3 is appropriate as 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 explicitly states the tool records a charge against a meter and enforces a cap. It uses specific verbs ('record', 'enforce') and distinguishes from siblings like meter_open and meter_status by highlighting the budget enforcement aspect.

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 explains when to use the tool (to charge a meter with cap enforcement) and implicitly when not to (e.g., to check status use meter_status). It explicitly notes this is for budget enforcement that an agent cannot trust itself to do, providing clear context. It could explicitly name alternatives, but the sibling list makes it clear.

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?

Discloses that SaSame holds no funds, timestamps and signs envelopes with ed25519 for offline verification, and returns a signed receipt. This adds significant context beyond the annotations (readOnlyHint false, etc.). No 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?

Three concise sentences front-loading purpose, usage, and key behavioral details. No fluff, every sentence earns its place.

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?

Covers purpose, usage, behavior, and return value. Lacks details on receipt format or verification steps, but given schema coverage and annotations, it is sufficiently complete for an agent to use.

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 covers 100% of parameters with descriptions. The description does not add extra meaning to parameters beyond what the schema provides. Baseline score 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 the tool opens a usage/budget meter in SaSame's append-only ledger. It uses specific verb 'Open' and resource 'usage/budget meter', distinguishing it from siblings like meter_charge and meter_status.

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?

Describes when to use: 'when a principal/orchestrator wants to give a sub-agent a capped budget'. It also clarifies what it is not (payment processor). Lacks explicit exclusions or alternative tool references, but the guidance is clear.

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 discloses key behavioral traits: it returns a signed statement (ed25519) and raw line items, explains verification with trust_pubkey, and notes that line items are not separately signed. This complements the readOnlyHint annotation by adding cryptographic detail without 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 two sentences, front-loaded with the core action and followed by essential details on verification. Every sentence adds value without redundancy.

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?

Despite lacking an output schema, the description thoroughly explains the return structure (statement with budget/spent/remaining/item-count, line items) and verification. With a single parameter and no nested objects, this is complete for an agent to understand the tool's 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?

The input schema has 100% coverage with a clear description for meter_id. The tool description does not add extra parameter semantics beyond the schema; it focuses on output. A baseline of 3 is appropriate given high schema coverage.

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 a meter's current state, including budget, spent, remaining, and line-item history. It distinguishes itself from sibling tools like meter_open and meter_charge by specifying the read-only nature and the signed statement feature. The verb 'Read' and resource 'meter' are specific.

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 use for checking meter state but lacks explicit when-not-to-use guidance or alternatives. However, the read-only annotation (readOnlyHint) hints at non-mutating use, and the sibling context provides implicit differentiation. A slight gap remains in directing agents away from this tool for write operations.

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. Description adds behavioral context beyond annotations, clarifying the records are measurement-only and lack SLA/endorsement, which is useful for understanding limitations.

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?

Single sentence, no wasted words, front-loaded with purpose. Efficiently conveys essential information.

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 simple read-only tool with no parameters and no output schema, the description is sufficiently complete. It covers purpose and key constraints (measurement-only, no SLA/endorsement), though it does not describe return format or pagination.

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?

No parameters exist in input schema, so baseline is 4. Description does not need to add parameter details and does not contradict schema.

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?

Description clearly states it returns public monitoring receipt candidates, with a specific verb ('return') and resource. It adds 'measurement records only; no SLA or endorsement' which distinguishes it from other receipt-related tools in the sibling list.

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?

Implies usage context by stating 'no SLA or endorsement', suggesting not to use when these are needed, but does not explicitly name alternatives or provide when-to-use 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?

The description discloses behavior beyond annotations: it states the tool is free, uses a specific OCR engine, returns a text preview and confidence score, and that full extraction requires payment. Annotations already indicate readOnlyHint=true and openWorldHint=true, and the description aligns with them, adding more depth about the tool's nature.

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 extremely concise, using two short sentences that front-load key information (FREE, action, algorithm). Every word is purposeful, with no redundancy or filler.

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 simplicity (one param, no output schema, annotations present), the description provides sufficient context: what it does, what it returns, and how it relates to the paid version. It could mention supported image formats more explicitly, but the schema covers that. Overall, it is complete for an agent to select and use the tool.

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 input schema already provides 100% coverage for the single parameter 'image_url', describing it as a public URL for png/jpg images. The description does not add new semantic detail beyond emphasizing the URL aspect, so it meets the baseline expectation without exceeding it.

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 extracts text from an image URL via OCR, specifies the algorithm (SaSame OCR/tesseract), and distinguishes itself from the paid 'full' endpoint (x402 /ocr/full). This provides a specific verb and resource with sibling differentiation.

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 frames the tool as free and contrasts it with the paid full extraction endpoint, giving clear context on when to use this version vs the alternative. It does not mention when not to use it among the listed sibling tools, but the paid alternative is effectively a sibling in the same API family.

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?

While annotations already provide readOnlyHint=true and openWorldHint=true, the description goes far beyond by detailing the verification mechanism: reconciliation across 2-3 providers, per-RPC values, block pinning, consensus verdict, and max deviation bps. It also warns about potential stale data from a single RPC. This adds rich behavioral context that annotations alone do not provide.

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: two sentences plus a parenthetical list of operations. It is front-loaded with the core purpose and key differentiator (multi-chain reconciliation). Every sentence adds value, with no unnecessary words or repetition.

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 complexity (6 parameters, no output schema), the description compensates well by explaining output structure (per-RPC values, consensus verdict, max deviation). It covers the verification logic, supported operations, and chain options. This is complete for a read-only tool with good annotations.

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% with all parameters described. The description does not add significant parameter-specific meaning beyond what the schema already provides (e.g., 'required for tx'). It frames parameters in the context of verification but does not enhance their semantics. Baseline 3 is appropriate as 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 it is a multi-chain onchain read that reconciles across 2-3 independent RPC providers. It lists the specific operations it handles (block_number, gas_price, balance, tx, erc20_balance, erc20_supply), making it distinct from other tools. The verb 'read' plus resource 'verified on-chain data' 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?

The description explains when to use this tool: for verified onchain reads that detect stale/different answers from a lone RPC. It implies its value for cross-provider consensus. However, it does not explicitly state when not to use it or mention alternative tools, such as simpler reads without verification. The guidance is clear but lacks exclusions.

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. Description reinforces this and adds that no checkout or charge is triggered. It also describes the return content, but the 'per referenced rail' part is inconsistent with no input parameters.

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?

Description is two sentences, front-loaded with the main action, and no unnecessary words. Efficient and structured.

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?

No output schema exists, so description must explain return values. It partially does (package overview and hosted checkout intake existence) but 'per referenced rail' is vague without input. Adequate but leaves gaps.

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 has 0 parameters, baseline is 4, but description mentions 'per referenced rail' which implies a parameter that does not exist, potentially misleading an agent. No additional meaning added to the empty schema.

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 returns a 'Factory Observation station package overview' and indicates hosted checkout intake existence. However, it mentions 'per referenced rail' without a corresponding input parameter, causing ambiguity. It does not differentiate from sibling tool 'get_pricing'.

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?

Description explicitly states it is read-only and no checkout or charge is triggered, providing usage context. But no guidance on when to use over alternatives like 'get_pricing' or when not to use it.

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 provide readOnlyHint=true. Description adds details on what the contract covers and a legal disclaimer, but does not reveal additional behavioral traits beyond what annotations signal.

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: first states purpose and contents, second reinforces read-only and philosophical context. Every sentence adds value, no redundancy.

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?

No parameters or output schema needed. Description fully explains what the tool does, its scope, and its limitations, making it complete for a read-only spec tool.

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?

Input schema has zero parameters and 100% schema description coverage. Baseline is 4; description adds no param info but isn't needed.

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 reads the provenance & rights passport contract and lists specific contents (evidence levels, signing roles, etc.). It distinguishes from sibling 'provenance_verify_passport' by emphasizing read-only nature.

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?

Explicitly declares read-only and clarifies it does not create/register copyright. Context about 'measurement only, not endorsement' helps usage. However, it does not explicitly state when not to use or compare to alternatives.

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, and the description reinforces read-only behavior and adds detailed behavioral traits: offline-compatible, checks specific cryptographic elements, and explicitly states it makes no legal ownership decision. No contradiction with 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?

The description is front-loaded with the core purpose in the first sentence, is about 60 words, and every sentence adds value (purpose, checks, read-only nature, SaSame context). 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 description explains what the tool does but omits return value details (e.g., whether it returns a boolean, a detailed report, or an error). Given no output schema, this omission affects completeness. However, parameter handling and behavioral context are well covered.

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 single parameter `passport` has a schema description ('Complete SaSame Provenance & Rights Passport JSON object') providing 100% coverage. The tool description adds no additional parameter-level details beyond what the schema already provides, so baseline 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 that the tool performs 'offline-compatible verification of a SaSame Provenance & Rights Passport JSON object' and lists the specific checks (claimant signature, artifact digest, event hash chain, etc.). It distinguishes itself from siblings like lookup_passport and provenance_passport_spec by emphasizing its verification and read-only nature.

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 usage for verifying a passport object and notes it is read-only, but does not explicitly state when to use this tool versus alternatives (e.g., lookup_passport for retrieval, provenance_passport_spec for specs). It provides sufficient context for a clear use case.

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 include readOnlyHint=true and openWorldHint=true, which the description matches by stating it returns structured JSON and does not return abstract full text. It adds details about stale flag and URL construction, but these align with annotations. No 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 4 sentences and front-loaded with the core purpose. It is concise but could be more structured (e.g., bullet points for output fields). Clear and efficient overall.

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 explains the return value well, lists the output fields, and notes the missing abstract. Without output schema, it compensates adequately. Could mention error handling or empty results but is sufficient for typical use.

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 baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions; it focuses on output fields instead.

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 'PubMed citation retrieval' and enumerates specific returned fields (PMIDs, title, journal, MeSH terms, etc.), distinguishing it from siblings like 'pubmed_lookup'. The verb is specific and the resource is well-defined.

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 use for structured citation retrieval, notes that abstract full text is not included, and references 'abstract_note' for further steps. However, it does not explicitly compare to 'pubmed_lookup' or specify when not to use.

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 provide readOnlyHint and openWorldHint. The description adds behavioral context by specifying it returns only titles, PMIDs, and journals, and that it is a limited preview without a paid tier, which is 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?

The description is two concise sentences that front-load the key information: it's a free preview of PubMed search and what it returns. No extraneous 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?

For a simple query tool with one parameter and no output schema, the description covers the main purpose and return items. It could mention ordering or limits, but overall it is adequate for a preview tool.

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 single parameter 'topic' is fully described in the schema as 'Biomedical topic or question'. The description adds no additional information about parameter format, constraints, or examples, so it stays at 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 it performs a real PubMed search and returns top article titles, PMIDs, and journals. It distinguishes itself as a FREE preview, differentiating from potential siblings like 'pubmed_evidence' which likely offer more extensive results.

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 implicitly indicates this is for quick previews by labeling it 'FREE preview' and noting 'No paid research tier is active'. However, it does not explicitly state when to avoid this tool or mention alternatives like 'pubmed_evidence'.

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 readOnlyHint=true are consistent with the description calling it an 'inspection station' that runs an audit and returns results. The description adds value by detailing what the report contains (evidence, remediation, certificate, next step) and clarifying it does not create a paid offer. No contradictions.

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 moderately concise, front-loading the main purpose and then listing outputs and usage notes. Some information could be streamlined, but it remains clear and contains no wasted sentences.

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 simplicity (single required parameter, no output schema), the description adequately covers inputs, outputs, and usage constraints. It mentions out-of-scope items and connects to sibling tools audit_mcp and get_pricing, making it complete for an agent to invoke correctly.

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?