AOTrust - PDR Notarization

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

No annotations provided, so the description carries full burden. It discloses that the server verifies payment and submits notarisation, returns job_id, and that polling via notary_verify is needed for the final result. Lacks detail on failure modes but is adequate for the 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?

The description is concise: two sentences plus a prerequisite line and flow step. It front-loads the core action and prerequisites. Could be slightly more structured (e.g., bullet points) but remains efficient and clear.

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 (6 parameters, 2 required) and existence of output schema, the description covers the main flow and return value (job_id). However, it omits explanations for optional parameters and potential errors, leaving gaps for a complete 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?

Schema description coverage is 0%. The description only explains tx_hash (required) and work_hash implicitly as the artifact identifier. It does not explain metadata, agent_sig, agent_pubkey, or artifact_uri, leaving their purpose ambiguous.

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: 'Submit a work artifact for on-chain notarisation (NEAR_DIRECT payment path).' It specifies the verb, resource, and payment path, distinguishing it from siblings like notary_notarize_paid by the payment method.

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 prerequisites: 'PREREQUISITE: Send the NEAR amount from notary_quote to the sink account, then provide the resulting tx_hash here.' Also outlines the overall flow: 'Step 3 of the notarisation flow: quote -> pay -> notarize -> verify.' Tells when to use notary_verify for polling.

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?

Without annotations, the description carries full burden. It discloses the key behavioral trait that the tool cannot be called via MCP and is for discovery only. This is valuable transparency. However, it does not mention other behaviors like side effects, authentication details beyond the payment flow, 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?

The description is somewhat verbose, especially with the detailed workflow instructions which may be better placed elsewhere. However, the length is justified by the need to convey the unusual non-callable behavior and alternative usage.

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 is complete enough for a tool marked as discovery only, providing a clear workaround. However, it does not mention what happens if called directly, does not reference the output schema, and does not address sibling tools or provide criteria for 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 description coverage is 100%, so each parameter is already documented. The description adds context that the tool uses x402 payment on Base, which helps understand the required 'work_hash' parameter. It does not elaborate on 'agent_sig' or 'agent_pubkey' 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: 'Notarize a work artifact with x402 USDC payment on Base blockchain.' It is specific about the resource and action. However, it does not explicitly differentiate from sibling tool 'notary_notarize' which likely does the same without payment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance, stating this tool is for discovery only and cannot be called via MCP. It outlines an alternative two-step workflow using POST requests. However, it does not compare to sibling tools or specify when to use this one instead of them.

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

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

With no annotations provided, the description carries the full burden. It discloses that the quote is valid for 600 seconds (expiration), returns cost and payment details, and is part of a multi-step flow. However, it does not explicitly state whether requesting a quote is free or if any side effects occur (e.g., rate limiting). The behavioral traits are mostly transparent but could be slightly more explicit.

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 long: the first concisely states purpose and key return values, the second succinctly positions the tool in a workflow. Every sentence adds value with 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?

The tool has an output schema (context signal), so return details are partially covered. The description lists return items (cost, quote_id, sink account, schema version) and provides flow context. It lacks explanation of the required work_hash parameter's format or constraints, and doesn't elaborate on pdr_version options. For a simple tool with 2 parameters, it is mostly complete but minor 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?

The input schema has 2 parameters (work_hash required, pdr_version optional with default), but schema description coverage is 0%. The description does not explain these parameters directly; it mentions 'work artifact' implying work_hash is the hash of that artifact, and 'PDR schema version' appears in the returns but not as a parameter explanation. It adds minimal meaning beyond the raw schema, failing to compensate for the lack of schema docs.

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: 'Request a notarisation quote for a work artifact.' It uses a specific verb ('Request') and resource ('notarisation quote'), and distinguishes itself from sibling tools by identifying it as 'Step 1 of the notarisation flow: quote -> pay -> notarize -> verify.'

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 defines when to use this tool: 'Step 1 of the notarisation flow.' It maps out the entire flow (quote -> pay -> notarize -> verify), implicitly explaining that subsequent steps have their own tools (siblings notary_notarize, notary_verify, etc.). This provides clear guidance on the tool's role vs 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?

Without annotations, the description discloses key behaviors: returns status, returns base64 PDR record when anchored, Ed25519 signature verification, and polling suitability. Slightly lacking on error conditions or side effects, but still strong.

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, no fluff. Front-loaded with the core action and immediate key details. 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 the tool has an output schema and is a straightforward verification, the description covers purpose, usage, return values, and flow position. No obvious gaps for an AI agent to understand how to use it 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?

Only one parameter (job_id) is described in the description as 'by job_id', which clarifies its purpose. The schema has 0% description coverage, but the description compensates 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 states exactly what the tool does: 'Verify a notarisation by job_id' and specifies the return values (status, PDR record with signature). It distinguishes itself from sibling tools by being step 4 of a 4-step flow.

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 identifies its position in the notarisation flow ('Step 4 of the notarisation flow: quote -> pay -> notarize -> verify') and states it can be polled until status changes from pending to anchored. This provides clear usage context.

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