See which MODELS are most used and trending by token volume, to pick a proven model. Optionally slice by period (day/week/month), modality, context_bucket, or by category / language_type (sampled weekly estimates). For app/product rankings use list-app-rankings instead.
| Name | Required | Description | Default |
|---|---|---|---|
| request | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral caveat — that category and language_type slices are 'sampled weekly send-stemations', which is valuable because those values are approximate rather than exact. However, it does not mention timing bounds, granularity limits (e.g. day not available with those slices), or any rate/pagination behavior, and since no output schema exists the response format 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?
Two sentences with a front-loaded purpose, followed by the optional slice summary and the sibling distinction. Every sentence earns its place, and the most important call-intention (the app/model split) is saved for the end as a closing routing note. It is compact and scannable.
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 7 nested parameters and no output schema, the definition is adequate but has gaps: it never states what the response looks off (e.g. per-model rank, token totals), how many results are returned, or how `total_tokens` is aggregated across the sampled and exact datasets. The nested schedule covers parameter mechanics well, and the description covers purpose the active trade-off, but the combination leaves an agent guessing at output structure.
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 at the top level is 0% — the single `request` wrapper parameter has no description, though its seven nested properties carry rich per-paramer text on defaults, restrictions, and data sources. The description partially compensated by naming the slice dimensions (period, modality, context_bucket, category, language_file) and flagging which produce sampled estimates, but it does not explain that all arguments must be nested inside `request` nor does it add per-parameter details beyond what the schema already states.
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 and resource ('which models are most used and trending by token volume') and a clear business purpose ('to pick a proven model'). It also explicitly names the closest sibling alternative ('For app/product rankings use list-app-rankings instead'), so an agent can immediately distinguish it from the one tool it could be confused with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete selection criterion (token-volume usage/trend, to pick a proven model) and calls out the key alternative (list-app-rankings) with an explicit 'instead'. It does not enumerate other nearby siblings like list-benchmarks or list-models, but the main confusion risk is addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools are clearly differentiated by resource and action: the eight list-* tools each target a distinct view (models, endpoints, rankings, apps, providers, presets, tasks, benchmarks), and cross-references between them reduce mis-selection. A few mild boundaries exist—list-models and list-benchmarks both include benchmark data, and install-ori-harness vs spawn-ori-eval are both Ori recipe tools—but their detailed descriptions mostly resolve these.
The naming is overwhelmingly consistent with a verb_noun pattern using the same prefix set: generate-, get-, list-, send-, along with install-, spawn-, search-, and transcribe-. The only deviation is ping, which is a standard bare health-check tool and does not follow the verb_noun convention.
At 22 tools, the set feels heavier than the ideal 3-15 range, though each tool is arguably purposeful given the broad surface: model catalog, rankings, benchmarks, presets, generation, audio, image, docs, uptime, credits, and Ori workflows. The variety justifies the size to some extent, but the sheer number puts it in borderline territory.
Core workflows are well covered: model discovery (get-model, list-models, list-model-endpoints), generation (send-message, generate-image, generate-speech, transcribe-audio), observability (get-credits, get-generation, get-endpoint-uptime-history), and docs. Notable gaps include no create/update/delete for presets and no persistent provider configuration methods, but these are workable since presets are dashboard-managed and providers can be pinned per request.
