okfindex

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally; 'does not create a charge' largely restates that. It adds no behavioral detail beyond annotations, such as what the summary contains or whether it hits live billing data.

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 tight sentence with the capability up front and the exclusion at the end. It is nearly a fragment, but nothing is 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?

With no output schema and no input parameters, the description is the only place to explain what a 'billing summary' returns, and it doesn't — no fields, scope, or account context. Adequate to avoid mis-invocation but incomplete for a tool whose value depends on its return content.

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?

Zero parameters, so the baseline of 4 applies. Nothing in the schema requires explanation and the description correctly avoids inventing parameter prose.

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 the resource (billing) and hedges it as 'payment discovery and billing summary', which is vague about what is actually returned. It does differentiate from purchase siblings with 'does not create a charge', but an agent still can't tell what billing data this surfaces versus, say, `pricing` or `api_access`.

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 alternatives named. The negative clause implies a contrast with the buy tools (`api_access_buy`), but the agent must infer that routing rather than being told 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered and the description needn't repeat it. It does add genuinely useful behavior — that low/example bundles (normally hidden from search) are reachable here, and what fields are returned. It says nothing about auth, rate limits, or behavior for a missing/invalid id.

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

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

Two tight sentences, front-loaded with the returned payload before the scoping caveat about live/low bundles. No filler, though terms like 'provenance' and 'repository signal' are left undefined.

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 the right thing by enumerating the returned fields, and it flags the non-obvious live/low behavior. The remaining gap is the undefined semantics of 'provenance' and 'repository signal', which an agent may need to interpret.

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 one parameter with 100% schema description coverage ('Bundle id, the `id` of every item in the list'), so the schema carries the semantics. The description adds no format, source, or lookup guidance for the id beyond what the schema already says — baseline 3 for high 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?

The description names a specific resource (one bundle) and enumerates exactly what the card contains — root index.md URL, version, concept count, provenance, repository signal — so an agent can tell it apart from search_bundles or list_listings by output shape. It never explicitly names the alternative, but the singular scope is unambiguous.

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 note that `live` and `low` (example/fixture bundles excluded from search) 'both answer here' gives a real usage hint: this tool reaches bundles search won't return. However, it never states the prerequisite (obtaining a bundle id from search_bundles) or when to prefer this over search_bundles, leaving usage only implied.

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 the safety profile is covered. The description adds value by specifying the returned statistics (size by provenance, last changed), but it does not describe response format, pagination, or any operational constraints. With annotations carrying the behavioral load, this is an adequate but not rich 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?

The description is a single concise sentence fragment with no wasted words, and it front-loads the core output content. It could be slightly clearer with an action verb, but it is efficiently sized for a no-param tool.

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?

Given no parameters and no output schema, the description should ideally explain the shape of the returned statistics. It does provide a high-level summary (size by provenance, last changed), but it leaves the exact response structure unspecified and does not clarify which index is being described, leaving a minor completeness 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?

There are zero parameters, so the baseline is 4. The schema is empty and the description does not need to explain any parameter semantics, making this dimension appropriately handled.

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 (the index) and the data dimensions (size by provenance, last changed), but it is a noun phrase without an action verb and does not differentiate itself from related siblings like mcp_index_signals or api_index. An agent can infer it is a stats endpoint, but the purpose is not sharply defined.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no context about what 'the index' refers to. The description only states what data is returned, leaving the agent to infer usage.

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 annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description starts from a lower bar. It does add one genuine behavioral fact not in the annotations — that the endpoint is free to call ('no charge') — but says nothing about freshness, caching, or the shape of the pricing data returned.

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 no filler; the content claim is front-loaded and immediately followed by the cost reassurance. Every clause earns its place.

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

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

For a zero-parameter, read-only lookup with no output schema, the description adequately states what is returned (public prices and free allowances) and that the call is free. Only the return format or freshness of the pricing data is left unspecified, which is a minor gap at this complexity.

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 nothing for the description to clarify. It appropriately does not invent parameter detail.

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

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

The description names the specific resource it exposes: current public prices and free allowances. It is clear what an agent gets back, though the phrasing is a label rather than a verb+resource statement, and it does not explicitly distinguish itself from sibling tools like billing or api_usage that could also look price-related.

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?

There is no explicit when-to-use guidance and no naming of alternatives (billing, api_access_buy, api_usage). 'No charge' is the only usage-relevant hint, signaling the call itself is free, but which tool to consult for actual account costs versus public list prices is 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: results are restricted to `live` bundles, the list terminates at offset 1000, and no total is returned by design. Those are real operational constraints beyond the structured fields, though return/pagination shape beyond `next_offset` is only lightly touched.

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 and information-dense, but it wastes budget repeating the free-text field list almost verbatim in two separate sentences ('free text over name, tagline, description and origin' vs 'Free text matches the name, the tagline, the description and the origin identifier'). The pagination note is also split across two places.

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

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

For a 12-parameter, zero-required search tool with no output schema, the description covers the key operational facts (live-only, pagination bounds, no total, where to get totals). It omits ordering-default behavior and result-shape detail, but nothing that would cause an incorrect invocation is clearly missing.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters including enums, defaults, and band formats. The description mostly restates this ('search root concept text', 'free text over name, tagline...'), adding little syntax or format meaning that the schema does not already carry. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Search the index of OKF bundles') and immediately scopes it: free-text fields, filter axes, pagination, and the `live`-only constraint. It is far more specific than a tautology, but it never names or contrasts a sibling (e.g. get_bundle for retrieval, mcp_index_search for a different index), so the agent must infer routing.

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 through mechanism rather than stated: 'Paginate with limit/offset', 'Only `live` bundles', and the pointer to `GET /api/okf/stats` for totals. There is no explicit when-to-use-this-vs-alternatives guidance (e.g. when to call get_bundle instead), so context is inferable but not spelled out.

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