Opedd

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

Annotations already carry the safe-read profile (readOnlyHint/idempotentHint/destructiveHint=false), and the description adds substantial context beyond them: output is a freshly-signed HS256 JWT verifiable offline against a canonical key, the embedded claims (iss/sub/iat/exp/jti/aud), the 365-day window cap, and the 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 core action and return format, and dense with actionable content, but it carries internal project references ('Phase 12 Wave 1 W1.4', 'INVARIANTS.md W1.6') that add 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 fully covers the return value (signed JWT with named claims), scope defaults, the hard window cap, auth requirements, and the boundary versus rsl_get. 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 parameters are already documented. The description only restates scoping semantics (content_id default license-wide, window cap 365 days) that the schema itself provides, 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+resource ('Issue a signed JWT attesting to EU AI Act Article 53 compliance') with the exact endpoint, and explicitly distinguishes itself from the sibling rsl_get (CDSM Article 4(3) reservation). An agent can pick it over any sibling 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?

Gives the concrete scenario ('artifact AI labs hand to legal/procurement for Article 53(1)(d) evidence') and an explicit when-NOT clause routing CDSM Article 4(3) obligations to rsl_get with 'never conflate'. Both the use case and the disambiguation are spelled out.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context beyond them: the 30-day-per-call window cap, that attestations are only Merkle-rooted once confirmed, and the exact auth paths required (buyer API key with 'audit' scope, buyer session, or connector sign-in). It does not discuss pagination behavior beyond the schema's 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?

Three dense sentences, front-loaded with what is returned, then the filter, then the constraints and auth. No filler or repetition of schema field names.

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 return-shape burden and does so ('each with its licence terms and on-chain attestation...'), plus range limits, filter semantics, and auth requirements. 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 coverage is 100%, so baseline is 3, but the description adds genuine semantic value the schema lacks: the 'at most 30 days per call' rule constrains what from/to may span, and the event_type filter values are put in context as 'event-class' selectors.

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: returns the account's audit records, one per licensed access, and enumerates the per-record payload (licence terms, Merkle root, inclusion proof). This is clearly distinguishable from sibling tools like list_licence_orders or get_compliance_dossier, which deal with orders and dossiers rather than access events.

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 usable context (filter by event_type, max 30 days per call, auth conditions) but never states when to reach for this tool versus list_licence_orders, get_compliance_dossier, or article_53_attestation. Usage is implied by the resource, not routed explicitly.

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 readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the safety profile is covered. Beyond that, the description adds substantive context: each call is recorded in the account's audit log, the 90-day cap and pagination behavior, and the required auth scopes/session types. This is meaningful behavioral disclosure above the structured hints.

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 return content, then layers window/pagination, audit-logging, and auth requirements in tight, information-dense sentences. Every sentence earns its place for a tool with this much operational nuance.

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 fully explains the return shape (row-per-article with metadata, terms, attestation, flags). Annotations cover safety, and the description covers pagination, window cap, audit logging, and auth requirements. 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 from/to/cursor are already documented in the schema. The description reinforces the 90-day window and mentions pagination via _meta.next_cursor, but does not add format or syntax detail beyond what the schema already provides. 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 (returns the account's compliance dossier) and enumerates the exact return shape: one row per licensed article with metadata, licence terms, on-chain attestation, and specific regulatory flags (EU AI Act Article 53, CDSM Article 4(3), TDM reservations). This clearly distinguishes it from siblings like get_audit_events, article_53_attestation, and verify_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?

Provides clear operational context: a 90-day window cap, pagination via _meta.next_cursor, and explicit auth requirements (buyer API key with 'audit' scope, buyer session, or Opedd connector sign-in). It does not, however, explicitly compare this tool to alternatives such as get_audit_events or article_53_attestation, so no exclusion guidance is given.

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

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

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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: result ordering, the per-line field set, the blockchain-anchored SHA-256 fingerprint disclosure, and the exact authentication scopes required. It does not describe pagination edge behavior, but that is minor against an already-strong annotation set.

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

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

Three sentences, front-loaded with purpose, then the order_id variant, then the access requirement. Dense and largely waste-free, though the field enumeration and the auth-sentence alternatives could be trimmed slightly without losing meaning.

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

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

There is no output schema, so the description correctly compensates by enumerating returned line fields and the extra Schedule/fingerprint payload for the single-order mode. Auth prerequisites and pagination are covered. Only minor gaps remain, such as what happens with an unknown or unauthorized order_id.

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, cursor and order_id are already documented in the schema itself (including 'max 100' and the next_cursor origin). The description adds only ordering information and a restatement of what order_id returns, which the schema already covers. Baseline 3 is appropriate when the schema carries the parameter detail.

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 ordering ('newest first') and the exact payload ('publication, licence, unit, price, quantity, status'). It also distinguishes the two modes (list vs. single order via order_id), so an agent can tell it apart from siblings like place_licence_order or verify_license 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?

The description clearly signals the two usage modes: omit order_id to page through orders, pass order_id to fetch one order with Schedule text and fingerprint. It also gives the precondition (buyer API key with 'audit' scope, buyer session, or Opedd connector sign-in). It stops short of naming an alternative sibling for related needs (e.g., audit events), so it is not a full 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?

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 already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the endpoint is public no-auth, that requesting jsonld:true embeds an HMAC-SHA256 signed receipt with a tdm:reservationSignedAt timestamp, and what the default response shape is. That is exactly the behavioral context annotations cannot carry.

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 purpose and the no-auth/discovery framing, and most sentences earn their place. It is dense with internal references ('Phase 12 Wave 1 W1.1', 'INVARIANTS.md W1.6') that add no value to an invoking 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 carries the return-value burden and does so: it enumerates the four license types and the tdm_reservation field, and distinguishes the JSON vs JSON-LD shapes. Nothing needed to call the tool 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why jsonld:true exists (regulators can post-hoc verify the reservation value and time) and confirms the default is the raw RSL Standard JSON shape. It does not add format detail for publisher_id beyond the schema's UUID/verified note.

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 a publisher's RSL Standard manifest via GET /rsl-manifest') and pins the exact shape returned (4 canonical license types plus the CDSM Article 4(3) opt-out posture). It also explicitly distinguishes itself from the confusable sibling article_53_attestation.

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

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

Gives an explicit when-to-use ('discovery surface ... BEFORE going through the buyer-account signup flow') and an explicit when-not ('It is NOT an EU AI Act Article 53 attestation ... via article_53_attestation tool'). The alternative and the condition that selects it are both named.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds meaningful extra context: the specific fields returned and the not-found outcome. It does not mention auth requirements or rate limits, so it falls short of 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?

Two tight sentences with the return payload described before the failure case — good front-loading and no wasted clauses. The first sentence lightly restates the title, which is the only inefficiency.

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 returned fields and states the negative outcome, which is exactly what an agent needs for a single-parameter lookup. Nothing material 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?

Only one parameter, and the schema already documents it fully (100% coverage) including the OP-XXXX-XXXX format. The description adds no syntax or format detail beyond the schema, 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 (checks/verifies) and resource (an Opedd licence key), clearly distinguishable from siblings such as purchase_license, list_licence_orders, and place_licence_order. An agent can tell what this does 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?

Usage is implied — verify a key you already hold — but the description names no alternatives or conditions (e.g., when to use this instead of list_licence_orders or get_audit_events). No exclusions or prerequisites are given.

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