Mifori CertAgent Trust Oracle

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: sub-50ms latency, no authentication/payment/rate limits, HMAC-SHA256 signature verification, and deterministic precedence behavior. These are operational traits the annotations cannot express.

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 dense paragraph, front-loaded with the core capability and cost/latency profile before the routing branches. It is long and clause-heavy, but nearly every clause carries actionable information; a bulleted split of the two modes would read faster.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is unnecessary, and the description instead covers what the schema cannot: cost, auth, rate limits, mode selection, precedence, and error behavior. For a zero-required-parameter dispatcher 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%, so the fields themselves are documented; the description goes further by defining the interaction contract (eval_id wins over agent_id, omitting both yields INVALID_ARGUMENTS) and by characterizing agent_id as a DID or target_bot_url with a historical, non-deduplicated scope. It stops short of explaining limit's effect on ordering or cursor behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource pair ('Retrieves and cryptographically validates a signed audit certificate') and immediately distinguishes its two operating modes by argument. An agent can tell it apart from get_agent_leaderboard or verify_agent_reputation without opening any schema.

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

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

Gives explicit argument-combination guidance ('Pass eval_id alone... or pass agent_id with limit'), a precedence rule when both are supplied, and an error condition when neither is. It also names three siblings and the exact condition that selects each, which is the strongest form of when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, but the description adds substantial context beyond them: free, unauthenticated, no rate limits, no cursor pagination, single-page snapshot semantics, and the two-key sort order (Synthetic IQ descending, latency ascending). These are operational facts an agent could not derive from the annotation block.

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?

Only three sentences and the purpose is front-loaded ahead of usage and alternatives. The sentences are long and slightly overloaded with parenthetical detail, but essentially no filler is present.

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 single-parameter read tool with an output schema, the description covers everything the agent needs: auth posture, rate limits, pagination behavior, ordering, dedup, and sibling routing. Return-value structure is correctly left to the output schema.

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% and the schema already documents the 1-100 range and default of 10, so the baseline is 3. The description earns an extra point by explaining the intended meaning of the extremes (limit=1 for best-agent selection, limit=100 to compare AAA/AA/B reliability tiers), which adds interpretive value the schema lacks.

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 first clause states a specific verb and resource ('Queries a free, unauthenticated single-page snapshot of top-ranked AI agents') and specifies the exact ordering and dedup semantics. It is immediately distinguishable from get_agent_certificate, verify_agent_reputation, and submit_agent_feedback, which are all named.

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 gives explicit routing rules: limit=1 for immediate task routing, up to limit=100 for tier comparison, and it names each sibling with the condition that selects it ('use get_agent_certificate to validate a specific eval_id ... verify_agent_reputation to run a fresh live audit, or submit_agent_feedback to report telemetry'). Nothing is left to inference.

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?

Goes well beyond the annotations: latency bound (<100ms), no authentication or payment required, the idempotent credit-grant side effect with the literal reward_status value, and the blank-field validation failure mode. Annotations only declare readOnly=false, idempotent=true, destructive=false; the description adds the side effects and preconditions those hints cannot convey.

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-loads the core action and side effect, then the routing guidance, which is good ordering. However, it is a dense, run-on pair of sentences that recycles the eval_id and suggested_metric examples already present in the schema, so it is not maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-shape explanation is unnecessary, and the description still covers the key observable outcome (credit granted). With idempotency, latency, auth, and validation all addressed, an agent has everything needed to invoke 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?

Schema description coverage is 100%, so all three parameters including the nested suggested_metric example already document themselves. The description largely restates the schema's eval_id sourcing and suggested_metric example rather than adding new syntax or constraints, so the 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?

States a concrete verb+resource ('Persists machine-to-machine telemetry or score disputes for an existing audit certificate') and anchors it to a specific identifier (eval_id). The purpose is immediately distinguishable from sibling tools like verify_agent_reputation or get_agent_certificate.

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 it ('after an audit to contest a score or report runtime drift') and names the three alternatives with the condition each serves. Nothing about tool selection is left to inference.

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 only cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false); the description adds real behavior beyond them: a <500ms timing expectation, SSRF guarding, an HMAC-SHA256 signed certificate persisted to a public ledger, a $0.005 USDC cost, and a side-effect-free first leg. It stops short of describing failure modes or rate limits, so a 4 rather than 5.

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 dense paragraph, front-loaded with the primary action and firing order, with no filler sentences — every clause conveys a constraint, cost, or routing decision. It is information-packed to the point of being heavy, which keeps it out of 5 territory.

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 an output schema present, return-value details are not required, and the description still covers the paid/free duality, prerequisites, cost, persistence, and sibling routing. An agent has everything needed to invoke it correctly on either leg.

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 the baseline is 3, but the description adds workflow meaning the schema cannot: omitting payment_proof yields a free PAYMENT_REQUIRED_402 invoice, payment_proof accepts either a Base Mainnet USDC tx hash or a reward_token from submit_agent_feedback, and agent_id binds the certificate to a DID across URL rotations. This is genuine value beyond the 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?

States a specific verb and resource ('Executes a live <500ms outbound HTTP POST challenge against target_bot_url to benchmark Synthetic IQ...'), plus the concrete artifacts produced (latency, schema compliance, hallucination risk, HMAC-signed certificate). It is unmistakably distinct from get_agent_leaderboard, get_agent_certificate, and submit_agent_feedback.

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?

Gives an explicit when-to-use ('Use before delegating tasks to an unverified endpoint') and names all three alternatives with the condition that selects each. The two-step call sequence is spelled out as when-to-call-with-what, leaving nothing to inference.

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