x207

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world. The description adds genuine context beyond them: which contract calls (get_circle, get_params) supply the record and rules, and the fallback behavior of using the contract view list_members when no read API is configured.

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 the tool's purpose and followed by data-source and unit details. Little waste, though the parenthetical contract-call names are dense and the unit note is more output semantics than purpose.

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 is returned (record, rules, members) and clarifies that credit amounts are string values in the smallest unit with 6 decimals. Given only two optional parameters and annotation coverage of the safety profile, this is close to 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 description coverage is 100%, so both parameters are already documented in the schema and the baseline is 3. The description adds no meaning for members_limit or members_status; its note about credit amounts in the smallest unit concerns returned values, not parameters.

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: an overview of one x207 mutual-credit circle covering its contract record/rules and its members. This clearly distinguishes it from epoch_report, order_status, and search_listings, though the member-listing portion overlaps with x207_member_inspect without an explicit boundary.

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

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

Use is implied by the word 'overview' and by describing what it aggregates, but there is no explicit when-to-use guidance or statement of when to prefer x207_member_inspect or x207_epoch_report instead.

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 establish readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real value by disclosing that the result is assembled from two distinct sources (an on-chain contract record and HTTP read-API endpoints), which implies multiple failure modes, but it never says what happens for an unknown epoch or whether the read-API portions can fail independently.

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

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

A single front-loaded sentence that leads with what the tool returns before listing sources; the parenthetical endpoint paths are dense but each earns its place by identifying the data origin. Slightly awkward nesting of clauses, but no filler 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 only two optional parameters and no output schema, the description carries the burden of conveying the return shape, and it does so by naming the four constituent pieces (contract record, summary, metrics, settlements). Only the failure/absent-epoch behavior is left unaddressed.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description's 'without epoch, the current epoch' merely restates the schema. The settlements_limit parameter is not mentioned at all in the description, so no new meaning is added beyond structured fields.

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

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

States a specific resource (one clearing epoch) and enumerates exactly what is returned: the contract record via get_epoch plus the read-API summary, metrics and settlements. It does not name a sibling to contrast with, but the enumerated sub-resources make it distinguishable from x207_circle_overview or x207_simulate_clearing 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?

The only guidance is an implicit default ('Without epoch, the current epoch'), which tells the agent how to call it with no argument but not when this aggregate report should be chosen over, say, x207_order_status or x207_search_listings. Usage is inferable rather than stated, with no exclusions.

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

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

The two read endpoints and conditional fallback to contract views are meaningful behavioral details beyond the read-only, idempotent, non-destructive annotations. It does not discuss source-dependent freshness, failures, or authentication, so it stops short of being fully comprehensive.

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 compact sentences put the resource and returned fields first, then describe the data-source fallback. The endpoint details earn their place, and there is no filler or repetition.

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 simple one-parameter read, the field list, annotations, schema pattern, and source fallback provide enough context for normal invocation. The absence of an output schema leaves response structure unspecified, while account semantics and any source-dependent differences remain thin.

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, the description needed to explain the sole account parameter. Embedding {account} in the member paths only indirectly establishes that it identifies the target member; it provides no identifier semantics, example, or way to obtain one, although the schema does supply the syntax pattern.

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 identifies a single circle member and enumerates status, stake, position, and credit limit, making the retrieval scope clear. "One member" implicitly separates it from x207_circle_overview, but it does not explicitly name or contrast any sibling.

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?

Inspecting one member's status and financial position is the implied use case. There is no explicit when-to-use guidance or routing to x207_circle_overview or another sibling; the API fallback is implementation guidance rather than tool-selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description usefully reveals the underlying read API path and the no-hash listing behavior, but says nothing about pagination semantics for `cursor`, result ordering, or listing size limits beyond the schema default.

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 compact sentences, with the mode-switching rule front-loaded and no filler. The opening clause is slightly awkward in phrasing but carries real content about the order's fields.

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 five optional parameters and no output schema, the description carries a reasonable share of the load by describing the shape of an order (parties, budget, milestones, status), which substitutes partly for a return schema. Pagination via cursor remains unexplained, a minor gap for a listing 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 coverage is 80%, so the schema already documents hash, limit, party and status. The description reinforces the hash-optional listing mode and that party/status are listing filters, but adds no meaning for `cursor`, the one undocumented parameter, and gives no format hints for the hash.

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 (service order of the circle's marketplace), enumerates what it carries (parties, budget, milestones, status), and discloses the backing endpoint GET /orders/{hash}. It clearly conveys the dual get-by-hash / list behavior, though the opening noun phrase reads more like a resource label than a verb-led statement of what the tool does.

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 explicitly states the two modes: supply a hash to read one order, omit it to list, and use `party` and `status` to narrow the listing. That is concrete when-to-use guidance. It does not mention when to prefer a sibling like x207_search_listings, leaving that routing to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description still earns credit by disclosing the default status filter of 'open' — a behavior that silently hides expired, cancelled, and filled listings — and by explaining the cursor/nextCursor pagination contract, neither of which the annotations convey.

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

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

Two compact sentences, with the resource identity front-loaded and the operational details (optional filters, status default, pagination) following. Nothing is redundant with the title and no sentence 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?

For an eight-parameter, zero-required read list endpoint with no output schema, the description covers the essentials an agent needs to call it correctly: default filtering and how to paginate. The remaining gap is the opaque filter semantics (wantType, class enums), which would matter for a caller building targeted queries.

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 description adds genuine meaning beyond the schema by explaining the pagination loop ('Use `cursor` from `nextCursor` for the next page'), which references an output field absent from the input schema. However, with only 50% schema description coverage, several parameters (wantType, wantClass, offerClass, cursor itself) carry no explanation in either place, and the description does not compensate — notably it never explains what class values A/B/C/D/X mean.

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 resource ('Listings of the circle's marketplace') and clarifies the domain precisely: 'what an account offers and what it wants.' Coupling that with 'read API GET /listings' makes the operation unambiguous. It does not explicitly contrast itself with siblings like x207_member_inspect or x207_order_status, but the resource is distinct enough that confusion is unlikely.

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 that filters are optional and that `status` defaults to open, which is real usage guidance for a caller who might otherwise assume all statuses are returned. It does not say when to prefer this over sibling tools or when a filtered query is more appropriate than browsing, leaving selection to inference from the resource name.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and "Changes nothing" is consistent with them. Beyond that, the description discloses real domain semantics: each edge nets a debt, direction is debtor-owes-creditor, and `cleared` is the amount to cancel in the smallest unit — context the annotations cannot supply.

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

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

Three short sentences, front-loaded with the core action, then the edge semantics, then the side-effect disclaimer. No filler or restated boilerplate.

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?

The high-level return is described (validity plus what would clear), which partly compensates for the absent output schema, and the nested edge shape is explained. However, for a simulation tool with no output schema, it omits what an invalid proposal looks like (revert/error vs boolean field) and leaves the epoch parameter unexplained, so an agent cannot fully 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?

Schema description coverage is 0%, so the description must carry the parameter burden. It does well on the nested edge fields (debtor/creditor/cleared, including the decimal-string smallest-unit convention that the bare pattern `^\d{1,38}$` does not convey), but says nothing about `epoch` — its meaning, valid range, or whether unknown/future epochs are accepted.

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 (simulate/ask) and resource (clearing for an epoch) and clarifies it is a dry-run query against the `simulate_clearing` view returning validity and amounts. It is clearly distinct from all listed siblings (overview, epoch_report, member_inspect, order_status, search_listings) by domain, though it never explicitly says so.

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?

"Changes nothing" implies this is a pre-flight check, which is useful usage context, but the description never states when to call it versus what it precedes or replaces. No prerequisites, no mention of any real clearing/submission path, so the agent must infer the workflow position.

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