Jid: the trust API for AI agents

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

With no annotations, the description carries the full load and does so well: it discloses the output shape (headline, recommendation enum, failed checks, lookup links), privacy behavior ('processed in memory and never stored'), determinism ('no AI'), and billing ('counts as 1 check with a key; free tier without one'). Genuinely rich beyond any structured field.

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 the action (paste headers) and the return contract, then the checks performed, then privacy/billing. Dense and mostly waste-free, though the parenthetical UI hints and the billing clause make it a touch crowded.

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 one-param, no-output-schema, no-annotation tool, the description covers invocation, output shape, privacy, determinism, and billing – everything an agent needs to call it correctly and interpret results.

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 practical operational detail beyond the schema: that headers should be copied from 'Show original / View source' and that the body is not needed. This meaningfully helps the agent collect the right input, though it doesn't add format specifics beyond that.

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 title and description together state a specific verb (check) and resource (an email's authenticity via SPF/DKIM/DMARC and lookalike detection), and the input format is spelled out ('Paste the raw headers... Show original / View source'). This distinguishes it clearly from siblings like screen or verify_business, which concern businesses rather than individual messages.

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 clear operational context – paste raw headers, not the body – and instructs how to surface results ('show the user the read first'). It's clear when to use it, but there are no explicit exclusions or named alternatives for cases like verifying a business rather than a message.

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, the description carries the full burden, and it does add real behavioral value by flagging data provenance: facts carry a source, verification date, next check and confidence, and owner statements are 'labelled self-reported'. It still says nothing about read-only semantics, permissions, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that opens with the resource and then enumerates the payload; every clause maps to actual returned content. Slightly dense but 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?

There is no output schema, so the description must convey the return shape, and it does so in detail (status, identifiers, facts with provenance, owner statements, matches, history). Combined with a fully documented single parameter, an agent has enough to call it correctly; only usage routing is missing.

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 single id parameter is documented with a concrete example (gland-pharma-limited-j9nehi) sourced from search_business. The description adds nothing about the parameter, so 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?

Names a specific resource (the full Jid file for one business) and enumerates the contents an agent will receive, so the purpose is unmistakable. It does not, however, distinguish itself from siblings like verify_business or screen, leaving the differentiator 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?

There is no when-to-use guidance and no mention of alternatives; an agent must infer from the name alone that this is the detail-retrieval step after search_business. No prerequisites or exclusions are stated.

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, the description carries the full burden and does disclose meaningful traits: the receipt is stored, cryptographically signed with Ed25519, immutable evidence of a past decision, and free of charge (no metering/cost concern). It does not cover failure behavior (unknown/expired receipt_id, authorization needed to read a receipt), which is the main remaining gap for an annotation-free tool.

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 verb/resource/key and followed by the payload contents and the routing disambiguation. Every clause carries information (signature scheme, returned fields, cost, sibling exclusion) with no 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?

For a single-parameter read tool with no output schema, the description usefully enumerates the returned fields and states cost and signature type, which is exactly what the missing output schema would otherwise need to supply. Only error/absence handling is unaddressed, 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 description coverage is 100% and the single parameter's schema already documents the 'rcpt_... from verify_business' format and origin. The description only restates that lookup is by receipt_id, adding no syntax, format, or validation detail beyond the schema, so the baseline of 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 specific verb (Retrieve) plus the resource (a stored, Ed25519-signed verification receipt) and the lookup key (receipt_id), then enumerates the payload (inputs, decision, reasons, fact ids, value hashes, rules version, time). The clause 'not a check' explicitly separates it from the sibling verify_business, so an agent can route without opening either 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?

'Use it to prove what was checked before an action' gives a clear use context, and 'not a check' rules out the obvious wrong use (treating it as a verification call). It stops short of a full when-to-use/when-not statement (e.g., whether receipts expire or when no receipt exists), so it lands at 4 rather than 5.

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, the description carries the entire burden and does so thoroughly: it discloses the return structure (signals with source/source_url/verified_at, three 0-100 scores, checks with evidence and lookup links, a headline read and recommendation), the cost ('counts as 2 checks'), the API-key requirement, the degraded path for personal webmail (individual_or_unverified, no scores), that a possible list match is only 'review', and that message is hashed and never stored.

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 when-to-call and the primary inputs before diving into the return shape and caveats, so the most decision-relevant content comes first. It is dense and much of the middle is a single run-on enumeration of outputs, which costs some readability, but almost every clause carries actionable 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 19-parameter tool with no output schema and no annotations, the description is unusually complete: it explains inputs, the output payload, scoring ranges, recommendation values, cost, auth requirement, and edge-case behavior. An agent would know both when to call it and what to expect back.

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 the schema already documents all 19 parameters including enums and formats. The description only loosely maps inputs ('the sender's e-mail or the company domain, the company name, the context') without adding format or interaction semantics beyond what the schema states. 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?

States a specific verb+resource ('qualify' a business that contacted you) and immediately scopes it to an inbound form submission, inquiry or outreach reply. It is clearly distinguishable from check_email, screen and verify_business because it describes a multi-source qualification report rather than a single lookup.

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 a clear trigger ('Before you engage with a business that contacted you') plus hard boundaries ('Businesses only', 'Requires an API key', 'Not for credit, employment, insurance or housing decisions about any person'). It does not explicitly contrast itself with the sibling tools (screen, verify_business, check_email), so the alternative-selection guidance is implied rather than stated.

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, the description carries the full behavioral burden and does so richly: it declares determinism ('no AI in the decision'), typical latency ('usually under a second'), the advisory nature of the verdict, how sanctions name matches are handled ('engage=false with manual review, never a finding'), billing ('counts as 1 check with a key; free tier without one'), and the full return shape including a receipt_id and user-facing 'read'. It also links to governing rules.

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 decision, then covers inputs, outputs, and operational rules. It is long but justified by the tool's complexity (16 optional parameters, no output schema). The single dense paragraph could be more scannable, but every sentence contributes actionable 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?

Given the complexity (16 parameters, no output schema, no annotations), the description is nearly complete: it explains the verdict, return fields, determinism, edge-case handling, billing, and how to present results. It does not cover every parameter's mutual precedence or the role of less common fields (e.g., signal, ip_asn), but the schema handles those, leaving only minor 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 100%, so the schema already documents all 16 parameters thoroughly. The description restates the main input options (domain, url, email, phone, company_name, context, amount, policy) and notes the default policy, but adds little meaning beyond what the schema provides; baseline 3 applies when 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 states a clear verb and resource: it gives a fast 'engage-or-not' answer for screening a lead, sender, vendor or website. It is specific about the decision it returns (engage true/false with risk, confidence, reasons, mitigations), but it does not explicitly distinguish itself from siblings like qualify_counterparty or verify_business.

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 states the context of use ('before you reply to, onboard, pay or buy from someone') and enumerates supported contexts (lead, inbound_email, partnership, vendor, purchase, marketplace_seller, agent_action). It also tells the agent how to act on the result (act on engage=true; on engage=false, show reasons and mitigations). However, it does not name alternative tools or state when not to use this one.

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, the description carries the full burden. It usefully discloses the return shape ('candidate files with status and match evidence'), which signals a fuzzy/non-exact lookup, but says nothing about result limits, pagination, permissions, or what happens when no match is found.

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 tight sentences with no filler; the capability and accepted identifier types come first, the return behavior second. Every clause 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?

For a single-parameter search with no output schema, the description covers what the tool does, what it accepts, and roughly what it returns. Only pagination/result-limit behavior is unaddressed, a minor 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 100% and there is only one parameter, so the baseline is 3. The description goes beyond the schema's generic 'Business name or registry number' by enumerating the accepted registry identifiers (FEI, LEI, SEC CIK, DUNS, NDC labeler code, state licence/entity number), which genuinely improves how the agent fills the field.

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 ('Find Jid business files') and scopes the accepted inputs precisely (name or any of seven registry-number types). An agent can distinguish this candidate-lookup tool from siblings like get_business_file and verify_business without opening a 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?

Usage is implied by 'Find ... returns candidate files', which suggests a discovery step before get_business_file/verify_business, but no alternative is named and there are no explicit when/when-not conditions. Adequate but the routing decision 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?

With no annotations, the description carries the full burden and does disclose substantial behavior: the decision enum values (proceed, review, stop, insufficient_data), the shape of reasons (requirement, met true/false/unknown, fact ids, source, verified_at, fresh_until) and a signed receipt_id, plus what happens when activity is omitted. It stays silent on auth requirements, rate limits, and whether results are cached/stale beyond fresh_until.

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 opening sentence and the return-contract sentences are front-loaded and earn their place, but the inline enumeration of all 16 activities largely duplicates the schema enum, bloating the description with content already in structured data.

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 correctly shoulders the return-value burden and does so in detail (decision values, reason fields, receipt_id, and the no-activity behavior). Given six parameters and a compliance use case, a note on prerequisites, auth, or freshness limits would make it fully 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 schema already documents all six parameters, and the baseline is 3. The description adds some meaning by clarifying the id-vs-name/registry-number fallback path and giving human labels for each activity enum value, but it does not explain amount/currency/jurisdiction beyond what the schema already says.

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 with an explicit decision context ('Check a business before an agent pays, signs, books, hires or buys') and details the returned decision vocabulary. It doesn't name or differentiate itself against siblings such as screen or get_business_file, so the agent must infer which is the pre-transaction check versus the file fetch.

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 a clear triggering context (before paying, signing, booking, hiring, buying) and explains the conditional behavior of omitting `activity`. However, no alternative tool is named for when you want raw status/facts or screening instead, so the routing decision is left implicit.

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