Opedd — Licensed Content for AI

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the HS256 signing scheme, offline verification against a canonical key, the embedded claims (license context, usage counts, Tempo Merkle root, sub/iat/exp/jti/aud), the 365-day window cap, and required auth (audit-scoped OPEDD_BUYER_TOKEN or OPEDD_BUYER_JWT).

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 and endpoint, then the return payload, then the critical scope disclaimer. Dense but nearly every sentence earns its place; the JWT claim enumeration and the INVARIANTS.md W1.6 citation are slightly verbose for a description field.

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 carries the burden of describing the return value, and it does so concretely (freshly-signed JWT with named claims and offline verifiability). Auth requirements, window cap, and scoping defaults are all present, leaving no gap an agent would need to guess at.

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 still adds meaning the schema does not carry alone by stating the default window is license-wide and reinforcing the hard 365-day cap, though it does not add format detail beyond the ISO 8601 notes already in 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?

Specific verb+resource: 'Issue a signed compliance attestation (a JWT) for a specific license' with the exact endpoint. It explicitly carves out scope against a sibling ('this is the buyer-side attestation ONLY... that lives on the rsl_get tool'), so an agent can distinguish it from verify_license, get_compliance_dossier, and rsl_get without opening schemas.

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 when to use it ('the artifact a buyer hands to legal/procurement as evidence of where its content came from') and explicitly when not to ('does NOT discharge a publisher's CDSM Article 4(3) reservation obligation'), naming the alternative tool and variant (rsl_get with jsonld=true). This is textbook when/when-not/alternative routing.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: it is public and requires no API key, which is an auth requirement an agent needs. It omits pagination/default-limit behavior, keeping it from a 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?

Three short clauses, zero filler: what it returns, the filters, then the auth posture. Front-loaded with the resource and scope, so an agent can decide quickly.

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, but the description states what the results contain (licences and the content they cover), which covers the return-value burden. Filters, defaults and auth are all accounted for; only result ordering/pagination detail is absent, which is minor for a read-only browse 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 three parameters documented (limit, article_id, publisher_id), so the schema carries parameter meaning. The description only restates the two filter names and says nothing about limit or UUID format, adding no value beyond the schema. Baseline 3.

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?

Specific verb+resource: 'Lists licences recently issued on Opedd and the content they cover,' which tells an agent exactly what comes back. It does not explicitly differentiate itself from close siblings such as list_licence_orders or verify_license, so it falls short of a 5.

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?

'Public; no key needed' plus the two named filters imply a browsing/discovery use case, but there is no explicit when-to-use statement, no exclusions, and no pointer to an alternative for related needs (e.g. list_licence_orders). Usage is inferable but not 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?

Annotations already declare read-only, idempotent, open-world, non-destructive, but the description adds real behavioral context beyond them: no auth required, hostname-matched platforms resolve in milliseconds while custom domains take a few seconds because the detector probes well-known endpoints in parallel. It also enumerates the returned fields and explains what archive_method/forward_method and instructions mean downstream.

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, endpoint, and auth model before behavior and return shape, and every sentence carries information. The internal build tag '(Phase 12 Wave 3 W3.1)' and dense parenthetical detail are minor noise for an agent.

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 usefully enumerates the return fields and their role, plus latency expectations. It leaves the semantics of the confidence value (scale/interpretation) unexplained, a minor gap for a detection 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% for the single url parameter, so the schema already documents it. The description's added detail (any well-formed URL works, hostname-match short-circuits the probe) largely restates what the schema description already says, meeting but not exceeding the 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?

States a specific verb+resource (detect the content platform behind a URL) and names the exact endpoint, plus enumerates the detection targets (Substack / Beehiiv / Ghost / Medium / Brevo / custom). It is clearly distinct from siblings like verify_license, lookup_content, and purchase_license.

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 clear context for use: public no-auth lookup on a publisher URL, returning the onboarding workflow inputs that Opedd's setup wizard consumes. It does not name an alternative tool or state when NOT to use it, so it falls short of explicit routing 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 and destructiveHint, so safety is covered. The description adds genuinely useful context beyond them: the 30-day-per-call window limit and the three accepted auth paths ('audit' scope API key, buyer session, or Opedd connector sign-in). It stops short of describing pagination or response shape.

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 most important content (what is returned) is front-loaded, followed by filter, limits and auth in efficient order. The sentences are dense but each carries information; 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?

With no output schema, the description correctly takes on the burden of describing return values (audit records with licence terms and attestation), plus filters, the time-window limit, and auth requirements. Only pagination/response-size behavior is left implicit, a minor gap 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?

Schema coverage is 100%, so the enum values and ISO timestamp formats are already documented. The description adds marginal value by restating the event_type options and imposing the 30-day constraint on from/to, but does not explain limit or cursor behavior beyond what the schema 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 ('Returns the account's audit records, one per licensed access') and details the record contents (licence terms, Merkle root, inclusion proof). It does not name or distinguish itself from any sibling tool, so it lands short of a 5.

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 via the event_type filter values and the 'at most 30 days per call' constraint, giving the agent a sense of how to scope a query. However, it never states when to reach for this tool versus alternatives like get_compliance_dossier or verify_license, and there are no explicit 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 readOnly/idempotent/non-destructive/closed-world, and the description still adds substantive context: keys are masked to a 12-char prefix post-issuance and never returned in plaintext, and the call requires OPEDD_BUYER_JWT with a stated rationale ('a key must never mint keys'). That auth constraint and data-masking behavior are not derivable from the annotations or the empty schema.

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 return payload in the first sentence, with use cases and auth constraints following in a logical order. It is on the long side and the three parenthetical use-case quotes are somewhat decorative, but every clause carries differentiating 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?

There is no output schema, so the description correctly compensates by enumerating the returned fields (enterprise_buyers row with contact_email, buyer_org, created_at) and the shape of the key list (masked 12-char prefixes). Combined with the auth requirement, an agent has everything needed to call and interpret this 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 tool takes zero parameters, so the baseline is 4; there is no parameter syntax the description needs to compensate for. The schema coverage signal is 100% on an empty object, so nothing is left undocumented.

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 ('Fetch the authenticated buyer's account profile + masked API key list') and even names the underlying endpoint GET /buyer-account. This clearly separates it from sibling read tools like verify_license or list_licence_orders, which concern licenses rather than the buyer's own account and key inventory.

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 three concrete trigger scenarios (post-signup verification, dashboard mental model, audit prep before rotation) and explicitly routes the agent elsewhere ('buyer portal at opedd.com/buyer') for mid-lifecycle license details such as filter_rules, billing, and payouts. The only gap is that it doesn't disambiguate against sibling MCP tools that might also surface buyer/license data.

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 readOnly/idempotent/non-destructive, but the description adds behavior they cannot express: each call is written to the account's audit log (an observable side effect), the 90-day hard cap with cursor paging, and the specific scope ('audit') and session requirements. That is substantive disclosure beyond the 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?

Three sentences, front-loaded with the return shape, followed by limits/pagination and then auth. No filler, no restatement of the title, and 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?

No output schema exists, yet the description describes the return structure (one row per licensed article with named fields), the pagination contract, the audit-log side effect, and all auth prerequisites. An agent has everything needed to call it successfully.

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 from, to, and cursor, including the inclusive-bound and 90-day-cap notes. The description reinforces the window cap and cursor behavior but adds no new syntax or formatting detail. Baseline 3 applies when the schema carries the parameter burden.

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?

Specific verb (returns) plus resource (account's compliance dossier) and an enumeration of the row contents: article metadata, licence terms, attestation, and compliance flags. This is distinguishable from siblings like get_audit_events or article_53_attestation 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?

Gives clear operational context: 90-day window cap, pagination via _meta.next_cursor, and the three acceptable auth paths (buyer API key with 'audit' scope, buyer session, Opedd connector sign-in). It does not explicitly state when to prefer this over a sibling such as article_53_attestation, so it falls short of a 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?

Adds significant context beyond annotations: token format, env var requirement, licence types, error codes, and NULL semantics for pre-2026-05-14 articles. Annotations already indicate read-only, idempotent, closed-world behavior, so this is thorough.

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 but includes several dense parentheticals and error codes. It is informative but somewhat verbose and could be reorganized for better flow.

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 all critical context: authentication, licence applicability, error conditions, response shape, and NULL handling. No output schema, but it explains the RAG-extended response fields adequately.

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 documents both parameters at 100% coverage. The description adds value by specifying token format (opedd_buyer_live_* / opedd_buyer_test_*) and env var fallback, plus the note that no separate order token 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?

Clearly states the specific action: retrieve the full body of a licensed article. It distinguishes itself from search_passages by noting that pay-per-request AI answers do not retrieve articles.

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 covers when to use (per-article Human republication licences, AI answers monthly, client display) and when not to use (AI answers pay-per-request → use search_passages). Also covers error conditions 403 SEARCH_ONLY_LICENCE and 403 ARTICLE_EXCLUDED.

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 idempotentHint=true, so the description does not need to restate safety. It adds real behavioral context beyond the annotations: the content contract per order type (included/discovery-only/metered), null content_body semantics, pagination, and delta-feed polling. It does not describe pagination mechanics such as next_cursor shape, but the schema covers cursor.

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?

Each sentence earns its place with contract and routing info, but the description is dense and front-loads implementation detail ('Phase 10 + 11') that does not help an agent select or invoke the tool. It is information-rich but could be trimmed.

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, paginated list tool with a 100%-covered schema and annotations, the description is complete enough: it covers content access modes, auth, pagination, and bulk alternatives. The only gap is inherit return-shape detail for the 'included' content contract, which is minor.

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 four parameters well. The description reinforces since, cursor, and order_id semantics, but the schema is doing the heavy lifting; 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 opens with a specific verb and resource ('List articles from a buyer's licensed catalog') and even cites the endpoint. It explicitly distinguishes itself from stream_feed_ndjson and get_content, so an agent can tell what this tool does versus its 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?

It names the alternatives and the conditions that select them: get_content for per-article text, stream_feed_ndjson for bulk pulls over 200 articles. It also gives credential/order_id prerequisites and the omittable-order_id case, leaving little 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 already cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds materially new behavior: required credentials (buyer API key with 'audit' scope, buyer session, or Opedd connector sign-in), newest-first ordering, and the registry fingerprint semantics. These are exactly the operational facts 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?

Front-loaded with the core purpose, then the order_id variant, then auth — a sensible information hierarchy. The parenthetical field list is dense but each element earns its place; only marginal tightening is possible.

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 compensates by enumerating returned line fields and the extra Schedule/fingerprint data in single-order mode, and it covers auth and pagination. 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 the baseline is 3. The description goes further by mapping order_id to concrete return behavior ('returns one order, each line with its Schedule text and the SHA-256 fingerprint'), adding meaning the schema's one-line field description does not convey.

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 (lists the account's licence orders) plus the ordering and per-line contents, which no sibling tool shares. It also disambiguates its two modes (list vs. single order via order_id), so an agent can tell it apart from place_licence_order and verify_license 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?

Provides a clear conditional: omit order_id to page through orders, supply order_id to retrieve one order with Schedule text and registry fingerprint. It does not name alternative tools (e.g., browse_registry, verify_license) or state exclusions, so usage is clear but not fully routed.

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 readOnly/idempotent/non-destructive annotations: it names the required credential (OPEDD_PUB_BEARER or legacy OPEDD_API_KEY), the 8,000-character body truncation, page size 20, and cursor-based pagination. These are exactly the operational facts an agent needs before calling.

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 core action, then credentials, then return shape, then the include_body workflow hook. Dense but organized; a few clauses (page size 20, cursor) duplicate the schema rather than earning their place in prose.

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 compensates by enumerating returned fields (titles, descriptions, pricing, sales statistics). Auth, pagination, truncation, and the cross-tool workflow to purchase_license are all covered, so nothing an agent needs to call this correctly 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%, so the schema already documents every parameter, including the include_body/id interplay, the limit cap of 20 under include_body, and offset being ignored. The description largely restates these facts (truncation, page size, cursor), adding little semantic value beyond the schema baseline of 3.

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 ('List all licensable articles for the authenticated publisher'), and the publisher-scoped framing distinguishes it from siblings like search_content, lookup_content, and browse_registry. An agent can identify this as the 'my own published content' listing tool without opening the 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?

Explicitly routes the agent: article IDs from this list feed purchase_license, and include_body=true is the way to verify a prior push_content write. It gives clear when-to-use context but never states when NOT to use it (e.g., vs. search_content for discovery), so it stops short of full alternative coverage.

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, so the safety profile is covered. The description adds real behavioral value the annotations don't: what the response contains (title, publication, licence types and prices) and the 'article is not on Opedd' negative case, which tells the agent to expect a miss rather than an error.

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, zero filler. The lookup mechanism is front-loaded, then the return values and the negative case follow in the same sentence. 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?

With no output schema, the description correctly carries the return-value burden and covers both the hit and miss cases. It stops short of mentioning error behavior, auth requirements, or whether non-Opedd URLs error versus return empty, but for a single-parameter read tool it is close to 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% with a single required 'url' parameter whose schema description already says 'canonical URL of the article or content to look up'. The description's 'by its web address' is slightly looser than the schema's 'canonical URL' and adds no new syntax or format detail, 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?

States a specific verb and resource ('looks up an article on Opedd by its web address') and enumerates the payload: title, publication, licence types, prices, plus the not-found case. It's clear enough to distinguish from search_content or get_content, but it never names a sibling to disambiguate.

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 phrase 'by its web address' implies you must already hold a URL, which suggests usage, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives like get_content or search_content. An agent must infer the routing.

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 write/non-idempotent/non-destructive, and the description adds substantial context beyond them: requires a buyer session (OPEDD_BUYER_JWT) and genuine terms_accepted=true per the MSA, returns the access key (only valid once paid) and hosted_invoice_url where the buyer pays, and guarantees non-offering publishers appear in `unavailable` and are never charged. This is exactly the kind of auth, payment, and failure-mode disclosure the annotations 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?

Purpose and cardinality are front-loaded, but the body is a dense run-on packed with nested parentheticals covering four licence modes and cross-references, making it hard to scan. Most sentences carry needed detail, but the structure could be broken up and the description is close to over-length.

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 6-parameter, multi-mode order tool with no output schema, it covers return contents (order, lines, access key, hosted_invoice_url), auth prerequisites, terms acceptance, and edge cases (unavailable publishers, monthly coverage window). Nothing essential to calling it correctly 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%, so the baseline is 3; the description adds interpretive value by explaining valid licence/billing_mode combinations and the monthly-answers temporal caveat ('only covers articles published from the day it starts'). It reinforces include_archive and quantity semantics but mostly duplicates what the schema already documents.

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 ('Place a licence order with Opedd for one or more publishers') and immediately scopes the cardinality ('one order = one licence and one billing mode'). It clearly distinguishes itself from list_licence_orders, purchase_license, and verify_license by describing order creation with per-publisher Schedules.

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 strong conditional guidance: self-serve buyers need no order for enterprise/per-answer pricing, include_archive is only for 'enterprise' + 'monthly', and each licence/billing_mode pairing is enumerated. It names related siblings (search_passages, stream_feed_ndjson) as context but never explicitly contrasts when to choose this tool over purchase_license or list_licence_orders.

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, so safety is covered. The description adds genuinely useful context beyond them: it is public with no key required, and it discloses the shape of the response (counts, licences, prices, samples). Pagination/rate behavior is left to the schema.

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 short sentences: purpose and payload first, filters second, access requirement last. No redundancy and nothing that fails to earn 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?

With no output schema, the description compensates by naming the returned fields, and it covers access requirements and the filter set. It omits pagination behavior and default ordering, but for a read-only list endpoint with fully documented parameters this is largely 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 100%, so limit, offset, category, verified and min_articles are all already documented with equivalent detail (e.g. the case-insensitive substring note is repeated verbatim from the schema). The description adds no syntax or format meaning beyond what the schema provides, 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 specific verb and resource ('Lists the publications on Opedd') and enumerates the returned fields (article counts, licences, prices, sample articles), which clearly separates it from siblings like search_content or list_publisher_content. It does not explicitly name a sibling alternative, so it stops short of a 5.

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 implies the browse/discovery use case through the filter list and notes 'Public; no key needed', which tells the agent it can call this freely. However, it never says when to prefer this over browse_registry, list_publisher_content or search_content, so usage remains inferred 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds useful behavior beyond them: the returned license key format, certificate URL, and the Handshake Email delivery. It stops short of warning that, given idempotentHint=false, a retried call likely creates a second charge — a notable omission for a payment tool, keeping it out of 5 territory.

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 action and payment mechanism, then layers returns, side effects, and the sibling routing in a tight sequence. Every sentence carries information, though the env-var sentence slightly overlaps with schema 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?

With no output schema, the description usefully compensates by naming what comes back (license key, certificate URL) and the out-of-band Handshake Email. Combined with explicit sibling routing for AI licences, an agent has enough to call correctly, though the retry/duplicate-charge risk of a non-idempotent purchase is unaddressed.

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 9 parameters including env-var fallbacks and the terms_accepted semantics are already documented in the schema. The description restates the env-var fallbacks (OPEDD_BUYER_EMAIL, OPEDD_PAYMENT_METHOD_ID) rather than adding new meaning, 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 specific verb and resource ('Purchase a content license from the Opedd protocol'), names the payment rail (Stripe), and adds concrete outputs (license key OP-XXXX-XXXX, certificate URL). It also draws a hard boundary against the sibling place_licence_order for AI licence types, so an agent can route correctly 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?

Explicitly scopes the tool to single-article Human republication licences (license_type 'human') and tells the agent to use place_licence_order for AI licences, which is its closest sibling. It also flags the env-var shortcut (OPEDD_BUYER_EMAIL, OPEDD_PAYMENT_METHOD_ID) so callers know what need not be passed each time.

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 real context beyond the annotations: the required bearer credential (OPEDD_PUB_BEARER / opedd_sk_ publisher key), the 1–100 batch ceiling, and the minimal required fields with published_at defaulting to now. It does not, however, explain the update-on-conflict behavior implied by the title 'Publish or update' and by destructiveHint=true / idempotentHint=true, so the consequence of re-pushing an existing article remains unstated.

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 compact sentences, front-loaded with the action and destination, then credentials, then batching limits. Every sentence carries operational information; only the closing 'no code, straight from your AI assistant' clause is marketing 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?

There is no output schema, so the description should cover the return contract for a batch operation — e.g. whether results are per-article, how partial failures are reported, and whether re-pushing overwrites. Those are unaddressed, leaving a real gap for a destructive, batch, non-idempotent-looking write even though auth and limits 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?

Schema description coverage is 100% and the schema already documents the array bounds, required fields, published_at default, and every optional field. The description restates the required trio and the default rather than adding format or constraint detail, so the 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 and resource ('Push your published articles to Opedd') plus the downstream purpose ('licensed to AI buyers'). It explicitly positions itself against the sibling list_publisher_content, so an agent can separate supply-side push from read-side listing 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?

Gives concrete conditions: onboard an archive, push new content, batch back-catalogues into multiple calls when over 100 articles. Names the companion tool list_publisher_content. It stops short of stating when not to use it or what to do if an article already exists.

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 cover the read-only/idempotent safety profile, and the description adds genuinely new operational context: public no-auth access, the JSON-LD/HMAC-SHA256 signed receipt semantics, and the post-hoc regulator verification purpose. It doesn't cover failure modes (e.g. unverified publisher) or rate limits, but the added behavioral detail is substantial.

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 core action and scope are front-loaded before the detail, and most sentences carry information. It is dense with internal references ('Phase 12 Wave 1 W1.1', 'INVARIANTS.md W1.6') that add little for a calling agent.

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 properly carries the return-value burden by naming the 4 canonical license types and the tdm_reservation posture. The exact response envelope is left unspecified, but an agent has enough to call and interpret the result.

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 both parameters are already documented, giving a baseline of 3. The description elaborates on the jsonld flag's purpose (signed receipt, tdm:reservationSignedAt) but largely restates what the schema already carries.

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 ('Fetch a publisher's RSL Standard manifest via GET /rsl-manifest') and scopes the audience (AI agents/crawlers). It explicitly contrasts itself with the sibling article_53_attestation, so an agent can separate the two without inspecting 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?

Gives an explicit when-to-use ('BEFORE going through the buyer-account signup flow') and an explicit when-not ('It is NOT a signed compliance attestation (which is buyer-side, JWT-auth, via article_53_attestation tool)'). The routing is unambiguous.

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 readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely new context beyond them: exactly which fields are returned (publication, prices, word count, short description), the guarantee that article text is never returned, and that no API key is required.

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 compact sentences, front-loaded with the core purpose and return contract before the syntax and pricing notes. Every sentence carries information; nothing is padded.

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 search tool with no output schema, the description covers return fields, the key omission (no article text), query syntax, and access requirements, while annotations carry the safety profile. It could mention result-limit/pagination behavior, but limit is already documented in the 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by documenting query syntax (quoted phrases and -word exclusion) that the schema's plain 'Search words' entry does not convey. This is real added meaning for the required 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?

States a specific verb and resource (full-text search of licensable articles on Opedd) and clarifies scope by noting it returns metadata only, never article text. This implicitly separates it from text-returning siblings like search_passages, but no sibling is named explicitly, keeping it short of a 5.

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 'Free; no key needed' note gives useful invocation context, and the query-syntax hints imply a keyword-search use case. However, it never states when to prefer this over siblings such as search_passages, lookup_content, or browse_registry, so the guidance remains implied rather than explicit.

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 well beyond the annotations, disclosing the billing model (per-publication charge, card billing, $25 increments, $500 new-account limit), free-answer accounting, 300-word/25% passage caps counted cumulatively, and 24-hour dedup caching. It also flags third-party content delivery in <opedd:passage> blocks, may_train=false, and the required 'search' scope, none of which the annotations 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?

The core purpose is front-loaded, and the dense billing, cap, and filter sentences each carry distinct, non-redundant information. The block is long and reads as a wall of text with no visual separation, but little of it is genuinely wasteful.

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 carries the full load and does so: it explains the return shape (cited passages), the <opedd:passage> wrapping, and the empty-result reasons. An agent has everything needed to call it correctly and interpret the response.

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 real semantics beyond the schema: unmatched publisher names surface in filters.unknown_publishers and 'search nothing', and undated articles are excluded when a window is set. These behaviors are not present in the 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?

States a specific verb and resource: returns licensed passages from publications that answer a question, each with a source citation. It is clearly distinguishable from generic retrieval, but it never names or contrasts against close siblings like search_content or get_content, so the agent must infer the boundary.

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 context is implied through the described filters, billing conditions, and the empty-result reasons ('no_licensed_publishers' / 'no_paid_access'), which tell the agent when the tool will and won't produce content. However, there is no explicit when-to-use guidance or routing to alternatives such as search_content, leaving the choice 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 already declare readOnly, idempotent, non-destructive behavior, but the description adds substantial context beyond structured fields: the content contract (full text only for AI training orders), usage_records sentinel behavior, the 1000 vs 5000 article discrepancy, and credential requirements. This is rich disclosure for a read-only export.

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?

It is front-loaded with the core purpose and every clause carries specific operational information. However, the single dense paragraph with heavy parentheticals and internal jargon ('Phase 11 M3', 'revenue-model bifurcation invariant') reduces readability without adding much for an external agent.

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 bulk-export tool with no output schema and full schema coverage, the description covers content contract, pagination, limits, credentials, alternatives, and SDK routing. An agent has everything needed to call 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 the schema already documents limit, since, cursor, and order_id. The description reinforces usage ('Use since for delta-feed', 'Use cursor to paginate beyond 1000') but adds little semantic detail beyond what the schema provides, so it sits at the baseline of 3.

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 gives a specific verb and resource ('Bulk-export a buyer's licensed catalog') and even names the wire format and endpoint. It explicitly distinguishes itself from list_feed and get_content, so an agent can select it without opening other schemas.

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 states exactly when to use this tool versus alternatives: use get_content for article text, use the Python SDK for real bulk-ingest pipelines, and use since/cursor for delta and pagination. Exclusions and conditions are explicit.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value beyond that by disclosing the return payload fields and, importantly, the negative outcome ("or that the key was not found"), which an agent needs in order to interpret a failed lookup.

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 sentence, front-loaded with the action and then the result content. Every clause earns its place, and the failure case is appended without padding.

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 carries the burden of describing returns and does so by listing the licence detail fields plus the not-found case. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret this 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 the single parameter already documents the format (OP-XXXX-XXXX), so the schema carries the parameter semantics. The description adds no additional syntax, case-sensitivity, or validation guidance, making the baseline 3 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 and resource ("Checks an Opedd licence key") and goes further by enumerating exactly what is returned. This clearly separates it from siblings such as purchase_license, list_licence_orders, and lookup_content, which either create orders or fetch content rather than validate a key.

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 only implied by the verb "Checks" and the required key parameter; there is no explicit statement of when to reach for this tool versus browse_registry, lookup_content, or get_compliance_dossier. No exclusions or prerequisites are given, though for a single-purpose key validator the intent is reasonably inferable.

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