aether-developer

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), yet the description adds substantial operational context: fetch mode latency ('tens of milliseconds') versus slower cross-company calls, the `quality_caveat` response marker, default fund/proxy form suppression, and the requirement of an issuer identifier in fetch mode. It also discloses a real behavioral quirk — the rerank profiles are deprecated aliases whose cross-encoder was removed.

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 and the two-mode distinction, and most sentences carry routing or constraint information. It is long and dense for a tool description, and the cross_company/quality_caveat behavior is explained twice (description and `scope` schema), which is mild redundancy rather than waste.

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 16-parameter tool with nested objects, enums, and an output schema, the description covers everything an agent needs: mode selection, issuer requirement, non-US routing, coverage limits, and when to expect degraded (caveated) results. Return-value detail is correctly delegated to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 88%, so the baseline is 3, but the description adds genuine semantics beyond the schema: omitting `query` is what triggers fetch mode, `issuer.company_name` is the required route for non-US issuers with no US ticker, and cross-company calls carry a caveat. Minor parameters (limit, fields, exclude_form_type) get no narrative treatment, keeping it just short of a 5.

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?

Opens with a specific verb+resource and scope ('Search SEC filings (10-K, 10-Q, 8-K, registration statements/prospectuses and press exhibits; S&P 500 coverage, ~10 years)'), then immediately splits the tool into two named modes. Coverage boundaries (US SEC plus Sweden/Japan/Korea) are stated, which distinguishes it from siblings like transcript_search and regulation_search without opening any schema.

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

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

Explicitly states when to use each mode: 'Use fetch when you already know WHICH document you want and only need its text' versus search mode passing `query`. It also names the alternative scope and when NOT to use it — 'Use scope=cross_company deliberately only for questions that are genuinely about many companies' — and warns to check for `quality_caveat` on those calls.

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, and the description adds substantial behavioral context on top: the quarter-end coverage window, the in-progress newest quarter with fallback to a prior quarter named in coverage_caveat, the 45-day filing lag, and the explicit statement that no email is available or should be inferred.

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?

Dense and front-loaded, leading with what a 13F book is before constraints. It is long for a single description and a few clauses (signatory/contact detail list) are marginally over-detailed, but nearly every sentence carries decision-relevant 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?

Covers lookup modes, coverage window, lag, fallback behavior, data limitations, and what is not returned, which is everything needed for an agent to call this correctly without an output schema. The one ambiguity it cannot resolve (exact return shape) is minor given the enumerated output fields.

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; the description nonetheless adds semantics beyond the schema, notably that partial manager names resolve to the largest matching filer and the alias behavior of issuer/manager fields. Some of this (largest matching filer) is echoed in the schema text, slightly limiting the added value.

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 ('an institutional manager's reported equity book from SEC Form 13F') and enumerates the outputs (top positions by value, QoQ share changes, new/increased/decreased flags). It explicitly disambiguates from the sibling: 'this tool identifies the FILING MANAGER, not the issuer held — for who owns a stock, use holdings_by_security.'

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 triggering example questions, both lookup modes (partial manager name vs exact CIK), and a named alternative with the condition that selects it (holdings_by_security for issuer ownership). Exclusion list ('no shorts, cash, bonds or non-US listings') further bounds when this tool is appropriate.

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 a safe read-only, idempotent operation, yet the description adds substantial non-obvious behavior: the newest quarter is still filling in, positions are aggregated per filer CIK (with the BlackRock 42-line example), one book per filer (13F-HR or HR/A restatement, add-ons excluded), USD normalization, and the total_value_usd double-count caveat flagged by coverage_caveat.

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?

Long but densely packed — the core 'who owns a stock' purpose is front-loaded, followed by examples, input modes, and caveats. Nearly every sentence carries operational weight, though the coverage/aggregation paragraph is heavy enough that some trimming is conceivable.

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 multi-parameter, nested-object tool with no output schema, the description covers scope, coverage window, aggregation policy, caveats, and 13F limitations (no shorts, cash, bonds, non-US). Nothing an agent needs to invoke it correctly appears 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 baseline is 3, but the description adds real meaning: ticker is resolved via CUSIP internally, cusip should be used when the ticker is unmapped, period defaults to the most recent loaded quarter, and issuer is an alias shape shared with financial_search/search. This goes beyond the structured fields.

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 — institutional holders of a security from SEC Form 13F — plus the ranking (position value) and the delta dimension (quarter-over-quarter share changes). It is clearly the inverse of the sibling holdings_by_manager, so an agent can select it without ambiguity.

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 triggering questions ('who are the largest holders of NVDA', 'which funds added or trimmed') and states the input modes (ticker or CUSIP). It implicitly routes against holdings_by_manager via the 'who owns a stock' framing, but never explicitly names when not to use it or points to the sibling by name.

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 (readOnly, idempotent, non-destructive, closed-world), so the description adds real value by disclosing that proxy mode consumes prepaid Aether credits per call and that costs are returned for budgeting. It does not cover pagination or result-shape behavior, but the credit-consumption disclosure is meaningful context beyond the annotations.

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 the core purpose, then mode semantics, then the practical budgeting instruction. No filler; every clause carries 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?

An output schema exists, so return-value documentation is not required, yet the description still notes that per-call credit costs are returned. Combined with mode explanations and sibling routing, an agent has everything needed to call this 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?

With 67% schema coverage, the description compensates by explaining the semantics of the mode values ('indexed' = free partner_search, 'proxy' = proxied calls) and clarifying that ticker filtering spans both indexed docs and proxy endpoints. The limit parameter is left to the schema, but the added meaning is substantive.

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 active marketplace partners (sellers)') and immediately explains the differentiated concept of partner 'modes'. It clearly separates itself from siblings partner_search and partner_proxy_search, which it names and describes.

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

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

Gives a clear usage condition: call this to obtain per-call credit costs before invoking partner_proxy_search, and explains that indexed mode maps to partner_search. It stops short of explicit when-not-to-use or exclusion criteria, but the routing context is strong.

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 substantial behavior beyond the read-only/idempotent annotations: each call consumes prepaid credits regardless of result count, credentials are held by Aether so the agent never sees URL or token, confirm_charge=false yields a dry-run quote, and a wrong ticker guess spends credits on the wrong endpoint. These are exactly the cost and side-effect disclosures an agent needs.

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 sentences, front-loaded with the core action, and every sentence carries operational load (cost model, credential model, routing rule, prerequisite). Some issuer guidance overlaps the schema description but the redundant phrasing reinforces the credit-loss risk rather than wasting space.

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

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

An output schema exists, so return values need not be explained, and the description covers everything else: prerequisites, cost model, credential handling, dry-run mode, and routing behavior. For a 7-parameter, credit-spending, open-world tool this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71%, and the description fills in the semantics that matter most: why issuer/ticker routing is preferred over query-text detection, that empty partners means no fan-out and no charges, and the legacy nature of ticker_filter. `query` and `limit` remain undescribed in both places, keeping this short of a 5.

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

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

States a concrete verb and resource: 'Route the agent's query server-to-server to one or more seller-registered API endpoints.' This is specific and actionable. However, it never contrasts itself with the closely named sibling partner_search, leaving the agent to infer which of the two routing tools to use.

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 prerequisite ('Use list_partners first to discover available endpoints and per-call credit costs') and a conditional routing rule ('Pass `issuer` when the question is about one company'). It also warns that partners must be chosen explicitly to avoid surprise charges. Missing an explicit when-NOT-to-use-this / partner_search distinction, so not 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?

Annotations already declare read-only/idempotent/non-destructive, so the bar is lower. The description goes beyond them by disclosing the returned shape (ranked chunks with per-document attribution and license terms), the `quality_caveat` triggered in cross_company mode, and the cost implications of unscoped searches.

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 the what-then-how-then-prerequisite ordering. Every sentence carries information, though the middle sentence packs scope default, quality_caveat, and ticker-coverage behavior together tightly.

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 an 8-parameter search tool with a nested issuer object and an output schema, the description covers the decision-critical pieces: issuer vs cross_company, quality_caveat, partners scoping, and the list_partners prerequisite. The legacy ticker_filter and profile/limit tuning are left to the schema, which is reasonable but leaves a small gap for the deprecation-adjacent flag.

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 75% and the description still adds real meaning: it explains the issuer-vs-scope interaction (partner coverage is declared by ticker, so a named issuer narrows results rather than relying on query-text detection), and frames `partners` as a cost-scoping lever. It does not touch limit, profile, doc_types, or ticker_filter, which the schema covers.

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 (Search) and a precisely scoped resource (marketplace partner documents published by registered sellers), with concrete examples of doc types. The seller-published scope is distinct from siblings like financial_search and regulation_search, and it explicitly names list_partners as a related-but-different tool.

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

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

Gives explicit conditional guidance: pass `issuer` when the question concerns one company, otherwise the call defaults to scope=cross_company and the response sets `quality_caveat`. It also routes the agent to list_partners for discovering sellers before scoping via the `partners` arg.

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, so the safety profile is covered; the description adds real behavioral context beyond them — the quality_caveat field emitted on unanchored searches, the relevance-only ranking in that mode, the latency difference, and how prefer_consolidated changes which text variant is returned. It does not discuss limit/pagination behavior, so not a full 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?

Front-loaded with corpus scope, then usage, then filters, in one dense paragraph with no filler sentences; every clause carries content. It is long and repeats the celex imperative already stated in the schema, which keeps it short of a 5.

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 10-parameter search tool with an output schema present, the description covers what the agent still needs: corpus boundary, anchor-vs-unanchored behavior, the degraded-result signal, and the narrowing filters. Return-value details are legitimately left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80% (baseline 3), and the description adds prioritization the schema cannot: celex as the mandatory 'anchor' equivalent to naming an issuer, article as a know-it-when-you-see-it filter, and the issuer-vs-cross_company default relationship. It reinforces rather than merely repeats the schema, though the raw field definitions for limit and profile remain the sole source.

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 (Search) and a precisely bounded resource (the text of EU financial regulation across a named 29-act corpus), enumerating the covered domains and the returned unit types (Article-paragraphs, recitals, annex blocks with breadcrumbs). It also explicitly carves out scope ('not all EU law'), so an agent can separate it from the sibling filing/partner/transcript search tools without opening any schema.

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

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

Gives explicit routing rules: ALWAYS pass `celex`, add `article` when known, and use `scope=cross_company` deliberately for genuinely corpus-wide questions, with a concrete example ('which acts impose a 72-hour incident-reporting deadline'). It also names the consequence of the wrong path (no celex -> whole-corpus, relevance-only, quality_caveat), which is exactly the when/when-not guidance an agent needs.

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

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

With annotations already covering safety (readOnlyHint, idempotentHint, destructiveHint=false), the description adds genuinely non-obvious traits: unknown fields are REJECTED with a 400 naming them rather than silently ignored, filters are forwarded rather than dropped, an omitted `corpora` is narrowed by filing filters, cross_company responses set `quality_caveat` that must be checked before trusting results, and each hit carries corpus/accession/URL/confidence/anchor_id.

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 then usage then parameter guidance, and nearly every clause carries operational information. It is a long single block, though, and the dense parenthetical asides (e.g. EU regulation's lack of issuer/form/quarter) make it harder to scan than a short structured list would be.

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 12-parameter, nested-object, multi-corpus tool with an output schema, the description covers the decision path (default vs cross_company vs fetch mode), the identifier requirement, the forwarding/narrowing rules, and the response's quality_caveat sentinel. Nothing an agent needs to call it correctly is absent.

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 schema already documents each field's format, so the baseline is 3; the description nonetheless adds cross-parameter routing semantics the schema does not (issuer is forwarded to every corpus so one named subject scopes filings and earnings calls together; fiscal_year forwarding and the empty-year ±1 widening; which filters reach which corpora). It stops short of adding syntax detail beyond the schema for most fields.

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?

Opens with a specific verb+resource ('Unified search across every Aether corpus') and enumerates the exact scope: SEC filings, Japan/EDINET, Korea/DART, EU financial regulation, and earnings calls/press-release exhibits, auto-routed and merged. It also names the sibling tools (financial_search / transcript_search / regulation_search) it is distinct from, so an agent can route 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?

Explicitly states 'Use this for MOST questions' and that the caller does NOT have to pick a corpus, plus a concrete failure mode (same-day 8-K earnings exhibits silently missed by filings-only search). It gives a named condition and prohibition for scope=cross_company ('only for questions genuinely about many issuers') and routes ownership queries away from search entirely to holdings_by_security / holdings_by_manager.

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 goes beyond that by disclosing the terminal status values (pending/indexed/failed/revoked) and, more valuably, the deprecation window for the legacy alias vespa_chunk_count — real lifecycle context an agent could not infer from annotations alone.

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, purpose front-loaded, no filler. The second sentence is dense with parenthetical detail about the alias, but every clause carries information rather than restating the title.

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

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

An output schema exists, so return-shape explanation is optional, and annotations cover the safety profile. Still missing for a list tool: pagination/result-size behavior, whether revoked or failed documents are included by default, and any hint about the required API key.

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 single required parameter seller_api_key has 0% schema description coverage and receives no mention in the description at all; nothing explains that it authenticates the seller or how it is obtained. Since it is the only parameter, one sentence would have closed the gap entirely.

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 documents this seller has published') and scopes it to the caller's own seller account, which cleanly separates it from seller_publish_document and seller_list_my_endpoints in the sibling set. An agent can identify the 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?

Usage is only implied by the possessive scoping ('this seller has published'); there is no explicit statement of when to call this versus seller_list_my_endpoints or the various search tools, and no prerequisites or exclusions are given. Adequate but leaves routing 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 safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description is not obligated to restate that. It adds genuinely useful behavioral context about data handling: secrets are never returned and only a `secret_configured` boolean is exposed, which is important for an agent reasoning about sensitive data. It does not mention pagination or rate limits.

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 short sentences, front-loaded with purpose and followed by the one non-obvious caveat about secret handling. 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?

An output schema exists, so return-value structure need not be explained, and the description still flags the one return detail that matters (secret_configured). Annotations cover safety semantics. What's missing for full completeness is any guidance on auth failure behavior, result volume, or pagination.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description never mentions the single required parameter, seller_api_key. Its name is largely self-explanatory, but the description provides no compensation for the coverage gap (no auth semantics, no scope implications).

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 ('List') and resource ('proxy endpoints this seller has registered'), with the possessive scoping making clear it returns the caller's own registrations rather than a global search. This implicitly separates it from siblings like seller_register_endpoint and partner_proxy_search.

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: an agent can infer you call this to inspect endpoints you already registered, but the description names no alternatives (e.g., partner_proxy_search for other parties' endpoints) and states no prerequisites or when-not-to-use conditions.

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

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

Annotations only say it is a non-read-only, non-idempotent write; the description adds the async worker model, the `pending` → `indexed` status lifecycle, version-replacement semantics, and the account-status gating that silently stalls indexing. This is exactly the kind of behavior an agent could not infer from 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?

Four sentences, none wasted, front-loaded with the action then the async lifecycle then the constraint. Dense and readable with no repetition of schema or annotations.

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

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

An output schema exists, so return-shape explanations are not needed, and the description fully covers the async/status/account-gating complexity. The remaining gap is the undocumented optional parameters, which leaves an agent guessing about license, doc_type, metadata, and ticker_coverage at call time.

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 only 22% (2 of 9 params documented), so the description must carry the load. It does add real meaning for external_doc_id (the dedup/replacement key), but title, license, doc_type, metadata, source_url, and ticker_coverage remain undocumented in both description and 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?

States a specific verb+resource ('Publish (or update) a document into the marketplace') and immediately expands scope to the async indexing pipeline. It is clearly separable from siblings like seller_list_my_documents and seller_register_endpoint.

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 the two usage modes (publish vs. update via re-publishing the same external_doc_id) and states a hard prerequisite (account must be status='active', pending_review queues indefinitely). It does not, however, name any alternative tool or contrast with other seller_* tools for edge cases.

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 it is a non-readonly, non-destructive, non-idempotent, non-open-world mutation. The description adds genuinely useful context beyond that: AES-256-GCM secret storage, server-to-server routing, agents never seeing URL/token, and the active-account routing requirement. It stops short of describing failure modes or rate limits, so not a full 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?

Four front-loaded sentences with little waste, leading with the core action and security guarantee. The '(Mode B)' fragment is dangling jargon, but otherwise the structure is tight.

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

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

An output schema exists, so return values need not be explained, and the description covers the security model and account prerequisite. However, for a 16-parameter mutation with only 25% schema coverage, it omits guidance on most parameters and any failure/validation behavior, leaving notable gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25% across 16 parameters, so the description carries a large burden, yet it only adds meaning for one field (price_per_call_usd_cents). Enums, auth_method, secret, pricing_model, request_template, and the many other params are left undocumented by the description.

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 names a specific verb+resource ('Register a proxy endpoint') and clarifies it is for sellers registering endpoints, distinguishing it from siblings like seller_list_my_endpoints and seller_publish_document. The parenthetical '(Mode B)' is unexplained jargon that adds no discriminating meaning for an agent.

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 a prerequisite ('Account must be status=\'active\'') which gives conditional context, but it never says when to choose this over alternatives or names any sibling. Usage is largely 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing the one-time API key return, the default pending_review state, the functional consequence (can publish/register but not surfaced in search), and the approval-bypass behaviour of invite_code. These are exactly the traits an agent cannot infer from 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 tightly packed sentences, front-loaded with the core action, then the one-time-secret warning, then the state machine, then the invite_code caveat. No filler and every clause carries operational weight.

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

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

An output schema exists so return values need little explanation, yet the description still flags the critical 'shown once' property. Account state, search visibility, and the invite_code escape hatch together give an agent everything needed to invoke this 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 60% and the schema itself already documents slug, description, and invite_code semantics. The description reinforces invite_code's purpose and adds approval-bypass context, but says nothing about org_name or contact_email, so it only marginally exceeds what the schema provides.

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 ('Create a new marketplace seller account') that is clearly distinct from every sibling (seller_publish_document, seller_register_endpoint, list_partners, etc.). The account-state explanation further pins down exactly what resource is being created.

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?

Explains the context in which this tool is used (new seller onboarding) and the condition for the invite_code path ('if the operator gave you one'). It does not name a competing tool, but none of the siblings is an alternative to signup, so there is little left to disambiguate.

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 safety (readOnly, idempotent, non-destructive), yet the description goes well beyond them: it discloses the `quality_caveat` field emitted for unscoped searches, the ±1 fiscal-year retry and its caveat, the latency/slowness delta for cross_company and the tens-of-milliseconds fetch mode, and the absence of ranking in fetch mode. This is exactly the behavioral context structured fields 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?

Long, but front-loaded with the core purpose and mode-selection rules before the parameter guidance, and nearly every sentence carries a distinct routing or behavioral instruction. There is mild redundancy between the description and the schema text for fetch mode and scope, which keeps it out of the top score.

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

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

An output schema exists, so return-field documentation is unnecessary, and the description still flags the single return field worth checking (quality_caveat). Given 14 parameters, nested issuer object, 4 enums, and two operating modes, the description covers every decision an agent must make before calling.

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 86%, so the schema already documents most parameters and baseline would be 3. The description still adds real semantics on top: issuer must be a ticker (not cik) in this corpus, fiscal_year is independent of and layered over date_from/date_to, and order='earliest' is the correct pairing for onset questions. Only limit/profile escape mention.

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 (search earnings-call transcripts and press-release exhibits) and immediately scopes it by speaker turn, with concrete examples of what is covered. The closing contrasts it against financial_search ('pair with financial_search to back narrative with filed numbers'), so an agent can distinguish it from siblings 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?

Explicit when-to-use (guidance, tone, forward-looking color filings lack), when-to-use-alternative (pair with financial_search), and an explicit warning that cross_company should be used deliberately only for genuinely multi-company questions. Fetch mode and onset/first-mention routing are each given their own selection condition, including the correct bound (date pair, not fiscal year).

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