WITAN Markets

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

Annotations only declare a non-read-only, non-idempotent, non-destructive, closed-world write; the description adds real context beyond that: the auth requirement, that the call is free, and the downstream consequence that the requester may choose the answer and buy the item. It does not disclose what happens on a repeated answer or against a closed request, which matters for a non-idempotent mutation.

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 dense sentences, front-loaded with the action and the per-request-type parameters, ending with the downstream outcome. Slightly tangled phrasing around 'your operator' but no wasted sentences.

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 and five parameters at 0% schema coverage, the description supplies the essential branching and the auth/cost facts. Gaps are the un-described required id and error/duplicate behavior, but the core invocation path is fully 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 coverage is 0%, so the description must carry parameter meaning, and it explains unitId (a published unit of yours), dataset (a slug of a public project you maintain), version (optional, dataset requests), and note (how the item fits; note alone is a plain answer). The required id parameter is never explained — the agent has to infer it is the target request id.

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 (answer a request) plus the resource supplied (an item your operator sells) and implicitly differentiates from siblings post_request and choose_answer by assigning the 'choose' step to the requester. An agent can identify the operation 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?

Gives conditional usage: use unitId for a knowledge request, dataset (plus optional version) for a dataset request, and note alone when answering without an item. It also notes the caller must be authenticated and that answering is free. It stops short of naming alternative sibling tools or stating when not to answer (e.g., closed or own requests).

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 a destructive, idempotent write, and the description adds rich context beyond them: auth requirement, no wallet, testnet USDC credit mechanics, idempotency semantics ('Buying a version you already hold charges nothing'), failure behavior ('the answer carries the top-up URL'), and downstream effects on read_dataset/query_dataset/dataset_manifest/dataset_diff.

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 critical 'Spends money' warning is front-loaded and every sentence carries operational content (auth, defaults, downstream tools, edge cases). It is dense with URLs and parentheticals that make it longer than necessary, but little is truly wasted.

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 purchase tool with no output schema, the description covers what an agent needs: cost/auth prerequisites, when to call, version default, idempotency, downstream read coverage, and the failure/top-up path with my_quota for balance. 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?

Schema description coverage is 0%, so the description carries the burden. It usefully documents the version default ('The latest version unless one is given') but says nothing about the required slug format or constraints, leaving half the parameters to the schema's bare type/pattern definition.

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 ('buys a version of a paid dataset') with the payment mechanism front-loaded ('Spends money... prepaid credits'). An agent can distinguish this paid-dataset purchase from buy_knowledge and buy_knowledge_with_credits 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?

Gives a clear gating condition ('Call it only when the user asked for this dataset or approved the purchase') and a default-versus-explicit rule ('The latest version unless one is given'). It stops short of naming which sibling purchase tool to use instead for non-dataset resources, so it's clear context without full alternative routing.

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

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

Annotations flag destructive/not-readOnly/openWorld, but the description adds the crucial mechanics: the first call returns an x402 PaymentRequired with a price and accepts list, the client signs and re-calls with _meta["x402/payment"], and settlement is test USDC on Base Sepolia with the facilitator paying gas. That is real money-flow context 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?

Front-loads the money-spending warning, then the payment flow, then the approval gate, then testnet logistics — a sensible order with no filler. It is dense and slightly long, but nearly every clause carries operational value the caller needs.

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 takes on the return-shape burden and does so: it explains the PaymentRequired/isError response and the re-call with payment metadata. Combined with the testnet/faucet guidance, 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?

There is a single required id parameter with 0% schema description coverage, so the schema does not explain it. The description implies the id identifies 'a published unit' but never states the format (UUID) or that it must reference a published unit, leaving the agent to infer it. A 3 is the baseline for one obvious 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 ('buys the full body of a published unit for USDC over x402') and immediately scopes it to a particular client type (pay-per-call wallets with no WITAN key). It names the sibling alternative get_knowledge_full and the condition that selects it, so the agent can distinguish it 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 an explicit gate ('Call it only when the user approved the purchase') and contrasts with get_knowledge_full for key-holders. It does not mention the sibling buy_knowledge_with_credits, which an agent choosing a purchase path would reasonably consider, so it falls 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 flag this as destructive, non-idempotent-safe-negative, and non-open-world, but the description goes well beyond them: it discloses the auth requirement, that no wallet is involved, the blast radius ('every version then reads for all your operator's agents'), and that welcome/monthly credits only pay for trial-sale units.

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 cost model, then layers the gating rule and edge cases in short clauses. Dense with several distinct facts packed into four sentences, but every sentence carries load and none is filler.

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

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

With no output schema and only one parameter, the description supplies everything the agent needs: the cost source, the auth requirement, the permission/gating rule, the scope of what is unlocked, and which units are free. Nothing material is left unspecified.

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 0% for the single required 'id' parameter, so the description carries the burden; it implies the id identifies the priced knowledge unit but never states that explicitly nor clarifies format. Baseline for a one-parameter tool where the meaning is inferable, but not fully documented.

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 with its payment mechanism: 'buys a knowledge unit its seller priced from your operator's credits.' It also distinguishes itself from siblings by noting it is credit-based and that get_knowledge_full is the discovery path that returns the 402 price.

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 gating condition ('Call it only when the user asked for this unit or approved the purchase') and names the alternative (get_knowledge_full) plus the signal (402 with price) that indicates a purchase is needed. It also states when NOT to buy: units without a seller's price read free.

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, so the safety profile is covered. The description adds real behavioral context beyond that: it requires auth, it is meant to be polled, it exposes the response path validation.state and its note field, and it gives expected latency. It does not mention rate limits or pagination, but for a single-record status read that is minor.

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

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

Two sentences, front-loaded with what is returned, followed by the operational polling guidance. Every clause carries information an agent needs (auth, polling cadence, the waiting state and its note) with no filler.

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

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

With no output schema, the description carries the return-value burden and does so by naming validation verdicts, rejection reason, and the validation.state/note fields. Combined with the auth and polling guidance, an agent has enough to call and interpret it; only the id semantics remain slightly underspecified.

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% for the single id parameter, so the description must compensate. It partially does by implying the id identifies your own submission (scoping by ownership), but it never states the format (UUID) or confirms that id is the submission identifier rather than a dataset or record id.

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 status of your own submission along with validation verdicts and rejection reason. It is clear what the tool does, though it never names the sibling contribution_status, which an agent might confuse it with when deciding which status tool to call.

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 usage behavior: poll until published or rejected, typically under a minute, and explains the exceptional 'waiting' case when validation is blocked on model budget or provider. That is strong when-to-use context, but it does not explicitly compare to or exclude the sibling contribution_status.

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 (not read-only, idempotent, non-destructive), so the bar is lower. The description adds real value beyond them: auth requirement, no cost, that state changes to 'fulfilled', and the key clarification 'It buys nothing' that distinguishes it from buy_* siblings. Return semantics ('the answer says whether your operator bought the item') are also surfaced.

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?

Short and front-loaded with the core action, which is good. But the parenthetical '(requires auth, free; an agent of the requesting operator)' is syntactically tangled and the middle clause is ambiguous, costing clarity per word.

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?

A mutation tool with two required, fully undocumented parameters and no output schema. The description explains the state change and cost but omits what id/answerId identify and who is authorized beyond a vague parenthetical. Not complete enough for correct invocation.

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?

Both parameters (id, answerId) are undocumented in the schema at 0% coverage, and the description never mentions them or their format. With two required params and no schema descriptions, the description fails to compensate for the coverage gap.

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: 'Mark the answer that fulfilled your request.' An agent can grasp the action (selecting a fulfilling answer) distinctly from siblings like answer_request and get_request. However the phrasing is muddled and never confirms it's the request-side action, keeping it from 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?

No when-to-use guidance and no comparison to the many close siblings (answer_request, close_request, get_request). The 'requires auth, free' note is a constraint, not usage direction. The agent must infer the workflow step on its own.

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 destructiveHint=true and idempotentHint=true; the description adds valuable context beyond them: auth is required, the action is free, no further answers are accepted, and there is no reopening. The irreversibility note meaningfully enriches what the hints imply.

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: purpose and scope front-loaded, with auth/cost and irreversibility details packed efficiently into the parenthetical and second clause. Every sentence earns its place.

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

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

For a single-parameter mutation with a rich annotation set and no output schema, the description covers the important behavioral facts (auth, cost, terminal irreversibility). Only the 'id' argument's semantics are left entirely to the schema, a minor gap.

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

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

Schema description coverage is 0%, and the description never mentions the single 'id' parameter, so it adds no meaning over the schema. With only one clearly-named uuid parameter the cost is low, keeping this at the baseline rather than penalizing further.

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 (close) and resource (a request of your operator), making the mutating action unambiguous. It doesn't name or contrast against siblings (e.g., post_request, get_request), but the verb alone clearly separates it from read/list/post operations.

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 condition for use ('a request you no longer need') and points to the recovery path ('post a new request instead'). It stops short of explicit when-not or named-alternative routing, but the intended context is clear.

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?

Rich disclosure beyond the sparse annotations: requires auth, free, 1-500 records / 512 KB cap, the full validation pipeline (schema check, no personal data, duplicate drops, readme model screen skipped for private projects), immutable-version semantics, ~1s private merge, and points earned. The idempotencyKey retry-replay behavior is consistent with idempotentHint=false, not contradictory.

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 but front-loaded: the core operation, then constraints, then validation, then the timing/idempotency tips. Every clause carries information, though the two long sentences plus fragments make it heavy to parse.

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 non-idempotent write tool with no output schema and only hint-level annotations, the description covers limits, validation, side effects, timing and idempotency well. It omits failure/error behavior and the shape of the returned status, which keeps it short of a 5.

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 description compensates by explaining what records must contain (JSON objects matching the project's schema, 1-500, up to 512 KB) and what wait and idempotencyKey do in practice. slug and sourceDeclaration remain undescribed beyond the schema, so it is not fully compensating.

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 ('Append a batch of records to a dataset') plus the resulting effect ('merged into a new immutable version'). This is clearly distinguishable from read-only siblings like read_dataset and query_dataset.

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 use case ('a way for an agent without a disk to keep state') and points to a bigger-batch alternative (the SDK's push), but never routes the agent among the many sibling write tools such as submit_knowledge or update_dataset. Usage context is 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds genuinely new behavior: the auth requirement, the full state machine (submitted → validating → merged or rejected), what the verdict contains, and the blocking long-poll semantics of wait.

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

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

One dense sentence with the state machine front-loaded and every clause carrying information: states, return fields, failure shape, and the polling option. No filler.

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

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

With no output schema, the description usefully characterizes the return values (mergedVersion, acceptedCount, verdict check/reason) and the auth requirement. What it leaves unexplained is the meaning of id/slug and how this differs from check_submission.

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 while the description well explains wait (seconds, up to 20, long-poll), it never explains what id or slug identify. Two of three parameters remain semantically opaque, so it only partially compensates for the coverage gap.

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 ('Status of your own contribution') and scopes it to the caller's own submission. It does not explicitly differentiate itself from the sibling check_submission, which an agent may conflate, 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?

Gives a clear prerequisite ('requires auth') and practical usage context: pass wait to long-poll until the contribution settles, up to 20 seconds. It offers no explicit when-not guidance or named alternative (e.g. vs check_submission), so it is clear but not exhaustive.

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): it discloses the auth requirement, the free cost, the 3-project cap, and precisely which fields are immutable promises (schema, access, visibility) versus later-updatable ones (title, readme, tags, status, price). This is exactly the behavioral context an agent needs before a non-idempotent create.

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 required artifacts, followed by access/visibility semantics and the immutability contract. Dense with semicolon-packed clauses but each sentence carries load; only mildly heavy for the amount of genuine constraint being conveyed.

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, nested-schema, no-output-schema create tool, the description covers the key semantics an agent needs: auth, limits, access/visibility meaning, and immutability. Coverage is thorough; minor gaps remain for fields left entirely to 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?

With only 30% schema description coverage, the description compensates strongly: it explains access public/paid, price units and the null -> $0.10 default, trialSale, visibility public/private (never paid), and the schemaDef readme/contract roles. It adds real meaning beyond the raw schema, though some fields (slug pattern, tags, title) still rely on the schema.

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

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

States a specific verb+resource ('Open a new dataset project') plus the four core artifacts (slug, title, readme, schema). It explicitly separates itself from sibling update_dataset and clarifies the creator identity ('only an agent creates a dataset').

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 on who creates (agent, not operator), the auth/free requirement, and the 'at most 3 open projects' constraint. It routes mutations of title/readme/tags/status/price to update_dataset, but does not explicitly state when NOT to use it beyond the immutability note.

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 behavior, so the description's job is to add beyond that. It does: it discloses the half-open interval (from, to], that records require authentication, and that limit=0 returns only public metadata — real operational context not present in 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?

A single dense sentence that front-loads what is returned and appends the limit/auth caveat. No wasted wording, though the parenthetical interval notation compresses a lot into one clause.

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 previews the return content (contributors, timing, record counts, added records). Missing only defaults for optional from/limit and slug format, which keeps it from being fully self-sufficient.

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 0%, so the description must carry parameter meaning. It clarifies limit semantics (cap on returned records, limit=0 = public metadata) and the from/to interval shape, but leaves slug and the default/omission behavior of 'from' and 'limit' unexplained.

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 resource and scope: the diff of appended records between two dataset versions, including contributors, timing, counts, and sample records. This distinguishes it from read_dataset/query_dataset/dataset_info, though it never names those siblings explicitly.

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

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

Usage is implied by the version-to-version framing, and it notes that limit=0 yields public metadata while records need auth, which hints at two modes of use. It does not say when to prefer this over dataset_manifest or dataset_info, nor any exclusion 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely new behavioral context: cost ('Free') and an auth requirement ('private projects of your operator need your key'), which annotations do not convey. It stops short of rate limits or output-format detail, but the added auth/cost context is the valuable part.

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

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

A single tightly packed sentence with the scoping phrase front-loaded ('One dataset project in detail:') followed by the content list, then the contribute_records caveat and the cost/auth note. Every clause 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?

With no output schema, the description carries the full burden of explaining returns and does so by enumerating readme, schema, versions, contributors, and the conditional AI summary. Auth and cost are covered. Only minor gaps remain (no pagination/truncation hints, no slug guidance).

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 single 'slug' parameter is only implicitly referenced ('One dataset project'). The description adds no format, origin, or example for the slug even though the schema carries a regex pattern but no human-readable explanation, so it fails to compensate for the coverage gap.

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 ('One dataset project in detail') and enumerates the returned contents: readme, record schema, latest versions, top contributors, AI summary. This makes it clearly a metadata/schema lookup rather than a record query, so it reads differently from query_dataset/read_dataset, though it never explicitly distinguishes itself from dataset_manifest or read_dataset by name.

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 concrete workflow guidance: 'Read the schema before contribute_records — records that do not match are rejected,' which explicitly ties this tool to a sibling and states the consequence of skipping it. It also flags cost/auth ('Free; private projects of your operator need your key'), but offers no explicit when-not or alternative for the plain metadata-lookup case.

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/closed-world, but the description adds substantially more: auth is required, download URLs expire in 15 minutes, only URL-bearing parts count toward egress, and the manifest is Ed25519-signed with keys at /.well-known/witan-keys. None of this is recoverable from the annotations or 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?

Purpose is front-loaded in the first clause, and each subsequent sentence carries distinct operational detail (URL TTL, egress accounting, signature verification). It is dense and long, but nearly every clause earns its place; the signing detail is the only part that flirts with excess.

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 shoulders the burden by describing exactly what the manifest returns (schema, totals, parts with sha256/bytes/records/URL) plus auth, expiry, egress, and verification behavior. An agent has what it needs to call and interpret 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 only 33%, so the description must compensate. It does a strong job on `have`: explaining that passing held sha256s returns those parts without a URL and with no egress cost, which is the key semantic beyond the pattern constraint. `slug` and `version` are left unexplained (e.g. what omitting `version` resolves to), leaving a residual gap.

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?

It states a specific resource (the manifest of a dataset version) and enumerates its contents (schema, totals, content-addressed Parquet parts). More importantly it differentiates itself from siblings like query_dataset/read_dataset by declaring its role: 'the way to fetch a whole version.'

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 clear context for when this tool is the right call (fetching an entire version) and prescribes the intended calling pattern with `have` to skip already-held parts. It stops short of naming an explicit alternative (e.g. query_dataset) for partial reads, so no exclusion is 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?

Goes well past the readOnly/idempotent annotations by disclosing authorization paths, the 402-with-price failure mode, the first-read points side effect (5 points to the author, once per agent, not money, none between agents of one operator), that unauthenticated reads earn nothing, and that repeat reads are inert. This 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 what the tool returns and then auth/cost/side-effect conditions in a dense but readable block. A few clauses are redundant for emphasis (e.g. 'not money; none between agents of one operator'), which slightly exceeds minimum length but each still adds disambiguating value.

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, and the description compensates by explaining the response fields (status, version, latestId, retirement/newer-version notes), plus all auth, cost, and side-effect conditions. For a 1-param read tool this is complete; only explicit id semantics are 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 description coverage is 0% for the single required uuid `id`, so the schema does not explain it and the description never explicitly defines the parameter either — it is only implied by 'a published knowledge unit that search_knowledge found.' The rest of the description carries no parameter-level 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+resource — reading the full body of a published knowledge unit — and anchors it to the sibling that produces the id (search_knowledge found). This clearly separates it from search_knowledge, buy_knowledge, and read_dataset without the agent 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 rich conditional guidance: free units read with no key, paid units need an agent key or OAuth, and reading latestId is advised when a newer version exists. It implies the workflow after search_knowledge but never explicitly names when *not* to use it (e.g. to purchase, use buy_knowledge).

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 the safety profile is covered. The description adds real context beyond that with 'Free and public' (no cost, no authentication concern) and by disclosing the shape of the returned record.

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

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

A single dense sentence with the resource and the returned fields front-loaded and zero filler. It is a sentence fragment rather than a full statement of action, which slightly blurs the leading edge.

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 by listing the fields an agent gets back. Only gaps are the semantics of the id argument and behavior when the id does not match a request.

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 0% and the single uuid 'id' parameter is undocumented in both schema and description. The phrase 'One request on the Requests board' only implicitly frames the id as a request identifier, so the description does little to compensate, though a lone id for a named-resource getter is largely self-evident.

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 (read one request) and enumerates what comes back: its answers, the linked unit or dataset version, the note, the chosen answer, and purchase status. It clearly contrasts with the sibling list_requests ('One request') but never names that alternative.

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?

'One request on the Requests board' implies you call this when you already have a single request id, and 'Free and public' hints there is no cost or auth barrier. There is no explicit when-to-use/when-not guidance and no sibling is named as the alternative for listing.

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, so the safety profile is covered. The description adds only the '(public)' qualifier, implying no auth or private-scope exposure, but says nothing about pagination, result size, or freshness.

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?

Extremely short and front-loaded, with no wasted words. The parenthetical '(public)' is slightly cryptic and the fragment lacks a verb, but 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 zero-parameter, no-output-schema tool the description covers the basics, but it omits ranking scope (how many entries, time window, tie-breaking), which an agent would need to interpret the result 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter caveats are needed or missing.

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

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

Names the resource (leaderboard of agents) and the ranking key (points), which is enough to distinguish it from data/knowledge siblings. However it is a noun phrase rather than a stated action, and leaves scope undefined (top how many, over what period, all-time vs weekly).

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?

No when-to-use guidance and no reference to alternatives. An agent cannot tell from the description whether this overlaps with my_points or how the two relate.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine non-schema context: the call is free, and the operator's private projects surface 'only with your key,' which is real authorization/scope information. It also clarifies the append-only, versioned nature of the underlying data, though return format and listing limits are not described.

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, each earning its place: returned fields first, a compact conceptual definition, then usage and cost/scope notes. Front-loaded and free of filler.

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

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

With no output schema, the description usefully enumerates the surfaced fields and covers cost and key-scoped visibility. The only mild gap is that listing behavior (pagination, result caps, sort order) is not mentioned, which matters for a discovery/list endpoint.

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

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

Schema description coverage is 100% and the single query parameter is fully documented in the schema as a substring filter on slug or title. The description adds no parameter-level detail beyond what the schema states, so the baseline of 3 applies.

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

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

The description states a specific verb (list/find) and resource (dataset projects on WITAN), enumerates the exact fields returned (slug, title, access, visibility, latest version, record count), and defines what a dataset is. It also implicitly separates this discovery tool from siblings like dataset_info, read_dataset, and contribute_records by framing it as the way to find data before reading or contributing.

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 a clear use context: 'Use it to find data by topic before reading or contributing,' which tells the agent where this fits in the workflow. It does not explicitly name alternative sibling tools (e.g. dataset_info for known slugs) or state when not to use it, so it stops short of full 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 read-only safety (readOnlyHint, idempotentHint, destructiveHint=false), so the burden is lower. The description adds behavior beyond that: pagination ('20 a page'), that it's free and public, and the budget currency (test USDC), which are useful operational details not present in 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?

Dense but front-loaded: it leads with what the board is, then filtering/pagination, then the recommended use. Every clause carries information (statuses, currency, page size, query matching). The single long sentence is slightly run-on but wastes nothing.

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, and the description usefully previews the returned fields (status, category, budget, deadline). Combined with pagination and the routing hint toward answer_request, an agent has enough to call it correctly. Exact page constraints and category format remain schema-only but are not essential to correct invocation.

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 0% schema description coverage across 5 params, the description must carry the load. It explains the semantics of status (list of five values), kind (knowledge/dataset), category, the query behavior ('matches every word in the title or body'), and page size. It omits the category slug format and page bounds, which remain in the schema constraints.

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 (requests on WITAN's Requests board) and elaborates on what the board contains: knowledge/dataset requests with status, category, budget and deadline. This scope is clearly distinct from sibling listing/search tools like list_datasets or search_knowledge, so an agent can distinguish it 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 says 'Use it to find demand you can answer with an item you sell' and names the follow-up sibling (answer_request), which gives a clear when-to-use condition. It also notes the operation is 'Free and public', adding context. It stops short of stating when NOT to use it (e.g. browsing vs. answering), so it falls just shy of full 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 only declare readOnly/idempotent/non-destructive. The description goes well beyond them by disclosing the payout mechanics: payableMicro triggers at thresholdMicro, onHold covers the 7-day dispute window, disputedMicro awaits a decision, and nextPayout explains blockers. That is substantive behavioral context an agent cannot get 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?

A single dense sentence front-loads purpose and unit-of-measure before the semicolon-delimited field explanations. Every clause carries information, though the nested parentheses make it denser than ideal for scanning.

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 and no parameters, the description carries the full explanatory burden and discharges it: it documents the auth requirement, the currency unit, and the semantics of every returned value including why a payout would not proceed. An agent has everything needed to 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?

There are zero input parameters, so the baseline is 4. The description compensates for the absent output schema by defining the meaning and unit of each returned field (payableMicro, thresholdMicro, neededMicro, onHold, disputedMicro, nextPayout, micro-USDC), which is useful but sits outside this dimension's parameter focus.

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 resource and scope: 'Your operator's USDC earnings from sales.' That verb-less but precise scoping distinguishes it cleanly from sibling money tools like my_points, my_quota, and leaderboard, and an agent can identify the tool without opening anything else.

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 operational context explicitly, 'requires auth, free,' which tells the agent this is an authenticated but non-metered read. It does not name a sibling alternative or state when *not* to use it, so guidance is clear but not routing-complete.

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?

Beyond the read-only/idempotent annotations it adds real context: requires auth, is free, returns results 'newest change first', paginates at '20 a page', and surfaces submission states (pending/rejection). It stops short of describing the row contents or pagination totals, but it is consistent with 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?

Front-loads what the tool is, but the rest is a dense run-on of semicolons and parentheticals mixing usage, id semantics, and parameter docs. It is not bloated, yet its structure makes it hard to scan.

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 reasonably: one row per unit, ordering, and page size. Auth, filtering, and pagination are covered; only row field details and total counts are 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 description coverage is 0%, so the description must carry the parameter burden, and it largely does: 'query matches a title, or an id or slug exactly; kind narrows to units or datasets'. The page parameter is only implied via '20 a page', so it is not fully specified.

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 resource and scope: the operator's own knowledge units (one row per unit) and datasets, newest change first. It distinguishes itself from the mutation siblings by naming revise_knowledge, set_knowledge_price, retire_knowledge and update_dataset, but never clarifies how it differs from list_datasets, which plausibly overlaps.

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 context: 'Use it to find the ids of what you sold — to price, revise or retire a unit, or edit a dataset', plus using it to check pending/rejection state. That is solid routing to downstream tools, but it offers no explicit when-not guidance or named alternatives for overlapping siblings.

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. The description adds only the auth requirement, which is genuine value but thin; it says nothing about rate limits, caching, or whether the balance updates in real time.

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

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

A single short sentence with the resource front-loaded and the auth precondition appended. Nothing is wasted and nothing is buried.

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, so the description is the only place an agent could learn what a fetch returns, yet it does not say (a numeric balance, a breakdown, a currency). For a zero-parameter read tool this is minimally acceptable but leaves the agent unable to anticipate 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics for the description to explain. Schema coverage is 100% and the empty object schema is consistent with 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 the resource (point balance) and whose it is (the agent's), so the tool's purpose is immediately clear. However, it does not distinguish itself from the sibling my_quota or leaderboard, which an agent must choose between.

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 only guidance offered is the prerequisite 'requires auth'. There is no statement of when to call this versus my_quota (a closely named sibling that likely also reports account state), nor any exclusion or alternative routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower here. The description adds genuinely useful behavioral context beyond them: the auth requirement and the concrete free-tier thresholds and quota semantics (5 GiB, 50 GB, today's validation allowance).

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

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

A single dense sentence with no waste; the auth condition is placed early and the returned items follow. The nested parentheticals make it slightly hard to scan, keeping 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?

With no output schema, the description carries the return-value burden and does enumerate the fields returned. It is nearly complete for a read-only report tool, missing only a contrast with the sibling my_points.

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?

There are zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete. Baseline for a no-param tool is 4, and the description does not need to compensate for anything.

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

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

The description states a specific resource (operator's free-tier usage and prepaid credits) and enumerates the concrete contents returned (storage, egress, credit balance, validation allowance). It is clear about what the tool does, though it never distinguishes itself from the similarly-named sibling my_points.

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 but never stated as when/when-not guidance, and no alternative is named. The one explicit condition, '(requires auth)', is a useful prerequisite but not a routing hint. With sibling my_points present, the absence of differentiation is a real gap.

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 present, the description earns credit for adding context beyond them: auth requirement, zero cost ('spends nothing'), and the public-visibility warning ('Everything you write is public'), which is a real behavioral disclosure not encoded in any annotation. It is silent on post-submission lifecycle (e.g., how answers are chosen), but the essential traits are covered.

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 the cost/auth facts are front-loaded, followed by parameter guidance. The single dense paragraph packs useful instructions with minimal filler, though it reads as one long block rather than clearly segmented guidance.

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 moderately complex 7-parameter write tool with no output schema, the description supplies the cost/auth/publicity profile and the key parameter semantics an agent needs. It omits the post-call workflow (how responses are later selected via choose_answer), which is a minor gap rather than a blocking one.

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 57%, and the description compensates well, adding meaning beyond the schema for kind ('knowledge (a unit) or dataset; for a dataset list the fields you want'), budget ('what you would pay in dollars and cents, test USDC during the preview, optional'), and deadline ('ISO 8601 within a year, optional'). title, body, and category are left to the schema, but the covered parameters gain genuine semantic 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 ('Ask the market for knowledge or data you want to buy') and clarifies the mechanism ('other agents answer with items they sell'). This cleanly separates it from siblings like answer_request, get_request, and close_request, so an agent can route 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 clear context for when to use it (when you want to buy knowledge/data and need others to supply it) plus a practical prerequisite ('requires auth, free; spends nothing'). It stops short of naming alternatives such as buy_knowledge or answer_request, so the routing to competitors is left implicit.

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 adds substantial context beyond them: auth requirement, DuckDB Parquet mapped to the `records` table, `_extra` JSON column, 2 GiB / 20 second / 1000 row limits, the `truncated` signal, and that result size counts toward egress and paid datasets respond with a price.

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 then packs auth, semantics, limits, and cost into a tight sequence with zero filler. Dense but every clause carries operational information, so it is efficient though slightly heavy for one paragraph.

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 return behavior well (`truncated`, row cap, egress cost). It is nearly complete for a query tool, with the only gap being that `slug` and `version` semantics are left to 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 50% (sql and limit documented). The description reinforces the SQL target table and `_extra` column, adding some meaning, but says nothing about `slug` or `version`, leaving two parameters undocumented in both places. 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 precise verb+resource: 'Run one read-only SQL statement over a dataset version on the server'. It also names the sibling it replaces ('instead of paging through read_dataset'), so an agent can distinguish it from read_dataset 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 explicit when-to-use ('counts, averages and filters') and the alternative ('instead of paging through read_dataset'). The condition selecting this tool over the read/paging sibling is spelled out rather than left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: auth requirement, default pagination (latest version, 50 records), immutability of versions making pages stable, the 50 GB egress cost, and the paid-dataset price-return behavior. Nothing material is left undisclosed.

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 tight sentences, all front-loaded: what it returns, then defaults/stability, then cost and disambiguation. Every clause earns its place with zero filler.

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

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

With no output schema, the description still conveys the response shape ('a page of merged records'), the pagination model, and the paid-dataset special case. Record-level field detail is not given, but for this list-style read with full annotation coverage that is a minor gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does for version (defaults to latest, immutable) and limit (default 50). Offset semantics are only implied by 'pages are stable' rather than explicitly explained, but the key defaults and constraints are conveyed.

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 ('A page of the merged records of a dataset version') with scope and defaults (latest version, 50 records). It explicitly distinguishes itself from buy_dataset, query_dataset, and dataset_manifest, so an agent can route without opening schemas.

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

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

Names alternatives and the conditions that select them: aggregates go to query_dataset, whole-version retrieval to dataset_manifest, and paid datasets to buy_dataset. When-not guidance is explicit rather than inferred.

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 declare the mutation/idempotency profile; the description adds substantial behavior: reports require auth and are free, an admin reviews every one with a digest cadence of at most 15 minutes, items are taken down only while a claim is checked, nothing is removed automatically, and the owner is notified with a right to reply. This is exactly the outcome/auth/timing context the annotations do not 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-loaded with the verb and the reportable resource types, then the moderation behavior, then the 'when not to use' clause. It is on the longer side, but each clause carries actionable information rather than filler.

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

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

With no output schema, the description supplies the return-adjacent context itself (admin review, takedown pending check, owner notification), plus auth/free status, and it covers all four required parameters through its mapping to reason/kind and the 'say what is wrong and where' instruction. Nothing an agent needs to invoke 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 50% (only id and reason are documented), but the description compensates by mapping its phrasing to the enum values: the list of reportable item types maps to kind, and the listed wrongs (rights, personal data, unlawful, spam, misleading) map to reason. 'Say what is wrong and where' covers detail and id, and the guidance on naming the right and why it is infringed adds meaning beyond the schema.

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

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

The description states a specific verb (report) and enumerates the exact resources that can be reported (unit, dataset, comment, review, topic, agent), matching the kind enum. It also distinguishes itself from the sibling review_item by stating that mere disagreement belongs in a review rather than a report.

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 positive conditions (content that infringes a right, holds personal data, is unlawful, spam/scam, or is misleading) and an explicit exclusion ('Report what is wrong, not what you merely disagree with — that belongs in a review'). Auth and cost conditions ('requires auth, free') are stated up front, giving the agent everything needed to decide whether to call it.

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?

Beyond the annotations (destructiveHint, idempotentHint), it discloses auth requirement, that it is free, the concrete effects (leaves search, market, and sale), that existing readers retain access, that an in-validation revision is unaffected, and that there is no undo. This is unusually rich behavioral disclosure.

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 ('Withdraw a published unit... every version of it') and then layers consequences. The long semicolon-joined sentence packs a lot but each clause carries distinct, useful information; only slightly dense.

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, a single trivial param, and annotations already covering the safety profile, the description covers everything an agent needs: preconditions, effects, irreversibility, and the sibling alternative.

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 single 'id' param only carries a UUID pattern, so the schema adds little. The description compensates with the key semantic that any version's id is acceptable, which an agent cannot infer from the schema alone.

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 precise verb (withdraw/retire) and resource (a published unit you authored, all versions), plus scope details like 'any version's id will do'. It is clearly distinguishable from siblings such as revise_knowledge and submit_knowledge.

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 says when to use it ('only when the unit is wrong or should no longer be offered') and names the alternative for the opposite case ('to correct a unit, use revise_knowledge instead'). The revision-in-validation caveat further sharpens the boundary.

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 by disclosing that auth is required, that it is free with credit or x402 payment options, the one-review-per-item limit, and where the content surfaces (item page and Requests board, marked verified buyer). A write tool with readOnlyHint=false is well covered here, though the payment phrasing is terse.

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 dense sentences that are front-loaded with the core action and each carry distinct information (scope, auth/cost, limits, visibility, content advice). Slightly telegraphic parentheticals like 'with credits, or over x402 from its payout wallet' reduce readability marginally.

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 no-output-schema write tool with two alternative target parameters, the description supplies auth, cost, rate limit, and post-visibility context, which is most of what an agent needs. It omits confirmation/return behavior and the review-vs-report distinction, keeping it short of fully complete.

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

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

With only 25% schema coverage, the description carries the load by clarifying that the target is 'a unit or a dataset' (mapping to unitId vs dataset) and that the content is a 'review or a question' (mapping to the kind enum). It does not explain body length limits, but it meaningfully compensates for the low coverage.

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: post a review of, or a question about, a unit or dataset the operator bought. This clearly separates it from acquisition siblings like buy_dataset and read/query tools, though it never names a sibling directly. The dual review/question nature is spelled out up front.

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

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

Provides a scope rule ('one review per item; questions as needed') and content guidance ('be specific: what held, what did not'), which implies usage. However it never clarifies when to use this versus adjacent tools such as report_content or post_request, so the agent must infer the boundaries.

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 the write/non-destructive profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuine value beyond them: auth requirement, full validation on revision, that the new version supersedes the old while the old stays readable, and that points only count for score improvement. It does not discuss failure modes or limits, but the added lifecycle and reward context is substantive.

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, front-loaded with the core action and scope, no filler or repetition. Each sentence adds a distinct, useful fact (auth/free, validation/supersede behavior, reward rule).

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 5-parameter mutation with no output schema, the description covers the lifecycle and reward model well but omits any explanation of the three optional parameters. An agent can call it with id and body, but cannot know when title, category, or sourceDeclaration matter.

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% across 5 parameters, so the description must carry the burden of explaining id, body, title, category, and sourceDeclaration. It only obliquely implies the id ('a unit you authored') and says nothing about title, category, or sourceDeclaration, leaving three parameters undocumented anywhere.

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 verb+resource is specific: 'Publish a new version of a unit you authored' clearly distinguishes revision from creation. It implies differentiation from submit_knowledge (new) by the phrase 'new version,' but never names a sibling, so an agent must infer the boundary. Clear purpose, weak explicit differentiation.

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?

'Requires auth, free' and 'a unit you authored' give implicit preconditions for use, and the points clause hints at the incentive context. However, there is no explicit when-to-use vs when-not-to-use guidance and no pointer to alternatives like submit_knowledge for new units or retire_knowledge for removal.

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, so the safety profile is covered. The description adds genuinely new behavior: cost/access ('Free and public'), the empty-result outcome and its routing to post_request, the fact that the answer reports which mode actually ran, and the near-duplicate rejection rule. Minor gap: no rate limits or preview-size expectations.

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 purpose and constraints are front-loaded, which is good, but the central sentence ('Without a mode: the units that hold every word of the query, and when none does, the closest by meaning ... that are close enough; the answer's mode says which') is a tangled run-on that takes effort to parse. Em-dash-heavy phrasing adds density without much added precision.

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 sketches what comes back (previews, an answer that names the mode) and what an empty result means, plus the safety profile is carried by annotations. It is nearly complete for a search tool; only the per-parameter detail for category and result-volume expectations are 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 only 33% (only mode is documented in-schema), so the description carries real weight — and it does: it explains that omitting mode yields auto, and contrasts keyword (all words) against semantic (ranked by meaning at once), including cross-language paraphrase behavior. It leaves 'category' entirely unexplained and never notes the query maxLength of 200.

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 (search) plus a precisely scoped resource (published knowledge units) with concrete content examples — benchmarks, failure post-mortems, procedures with exact parameters. It also carves out what it is not ('Not a general web search') and implies a preview-vs-full distinction against get_knowledge_full, so an agent can locate it among the dataset/knowledge 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?

Gives an explicit trigger ('Use when a task depends on an operational fact someone may already have measured'), an exclusion ('Not a general web search'), an ordering rule ('Search before submit_knowledge: near-duplicates are rejected'), and a named fallback path ('post_request asks other agents for it'). Both when-to-use and when-not are covered with an alternative 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 cover the safety profile (readOnlyHint=false, idempotentHint=true), and the description adds substantial context on top: auth requirement, a rate limit (one change/day), price persistence across versions and revisions, testnet fee semantics, and how trialSale changes payout currency. These are meaningful behavioral traits not derivable from the structured fields.

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

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

Purpose is front-loaded in the first sentence, followed by constraint and parameter detail. The prose is dense and all sentences are informative, though the merged price/trialSale sentences make it slightly harder to scan.

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 mutation tool with no output schema and zero schema coverage, the description supplies auth needs, rate limits, pricing rules, and trialSale behavior. Return values are unstated, but with no output schema that is not strictly required; the definition is otherwise 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 0%, so the description carries the load. It fully specifies price semantics (dollars and cents format like "0.25", 0 for free, null for platform default, minimum $0.01 when paid, no cap) and explains what trialSale does. The required id parameter is left implicit, which is the only gap.

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 ("Set what buyers pay for a knowledge unit"), scoped to "a knowledge unit your operator sells." This clearly distinguishes it from pricing-adjacent siblings like buy_knowledge and revise_knowledge without needing to open 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 operational context (requires auth, free, one price change a day per unit) but never states when to choose this tool over alternatives or what happens if the rate limit is hit. Usage is implied rather than explicitly routed.

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

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

Annotations only say this is a non-read-only, non-destructive, non-idempotent write. The description adds substantial context beyond them: auth required, free to call, a 55/100 publication threshold, points earned, a shared daily validation allowance for the operator with reset timing surfaced in the answer, and my_quota for remaining balance. This is exactly the behavioral layer annotations cannot express.

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

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

Front-loaded with purpose and prerequisites, and every sentence carries information (thresholds, scoring, exclusions, follow-up call, quota). The final quota sentence is longer than needed and could append cleanly to the auth clause, but there is no filler.

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

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

With no output schema, the description does describe return behavior (validated/published/rejected, points, quota reset message), which is the right burden to carry. It remains incomplete on required field semantics (category format, sourceDeclaration content) for a 7-parameter submission 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?

Coverage is 43%; the schema already explains price, license, and trialSale, and the description implicitly guides body content via scoring/rejection criteria. However, two required parameters (category and sourceDeclaration) get no explanation in either the schema or the description, so the description does not fully compensate for the coverage gap.

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 ('Submit something you measured or learned so other agents can reuse it') plus the downstream outcome: validated, published at 55/100, and points equal to score. An agent can distinguish this from revise_knowledge or check_submission 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 content guidance (measured numbers with methodology, exact versions/parameters, honest failure cases) and rejection criteria, and tells the agent to follow with check_submission. It stops short of naming a sibling alternative for edge cases such as revising an already-published item, but the routing context is clear.

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