Olaverse Lab

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

With no annotations, the description carries the full burden: it discloses that answers come with calibrated probabilities and that the model works across 19 named languages, which is useful beyond structured data. It omits practical behavior such as how many questions can be batched, latency/cost implications, determinism, or whether questions can be open-ended.

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 is front-loaded in one sentence, followed by structured per-parameter definitions and compact examples, so almost every line earns its place. The formatting is dense but functional rather than 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 tool with nested objects, 0% schema coverage, no annotations and no output schema, the input side is well covered but the return shape is never described — how choice probabilities or score distributions are returned per question_id is left unclear. An agent can construct a call but cannot confidently predict the response format.

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 'state' has only a title, so the description does the heavy lifting: it defines state as a string or JSON record and documents the questions map with three question types and concrete example payloads. It still leaves gaps such as how question_id keys map to results and any constraints on criteria keys or list ordering.

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 action — answering typed questions about a message, ticket, record or form — and returns a calibrated probability, which is distinctive versus siblings like extract_document or generate_questions. It never explicitly names or contrasts those siblings, so an agent must infer the boundary rather than being told.

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

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

Usage is only implied through the examples of question types; there is no explicit 'use this when' or 'use X instead' guidance, and no exclusions relative to generate_questions or extract_document. The three question-type examples do make the intended application reasonably inferable.

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 no annotations, the description carries the full burden and mostly does: it discloses the model's bias (African-first, traffic-weighted default), a known strength (short text), and the response fields. It omits operational traits such as determinism, latency, or input-size limits.

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

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

Two tight paragraphs: identity and domain first, then parameter and return semantics. The parenthetical qualification is compact and every sentence adds information; nothing is redundant.

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?

There is no output schema, and the description compensates by listing the return fields (ISO 639-3 code, script, name, confidence, runners-up). For a three-parameter utility, the only material omission is the meaning and bounds of 'top_k'.

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 compensate. It does well for 'mode', defining both values where the schema has only a bare string with a default, and 'text' is self-evident, but 'top_k' is never mentioned directly — only hinted at via 'runners-up'.

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 ('Identify the language of a text') with concrete scope ('among 608 languages') and domain character ('built African-first; good on very short text'). Siblings (decide, extract_document, generate_questions, restore_diacritics) are unrelated tasks, so no ambiguity arises.

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 real decision guidance for the two modes: 'traffic' for user messages and chat versus 'coverage' for building corpora. It does not name alternatives or exclusions, but there is no sibling that overlaps with language detection, so this is clear context rather than a 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 zero annotations the description carries the full burden and does substantial work: it discloses the >60,000-character chunking and parallel-merge behavior, warns the call can take minutes, states missing values return null, and interprets the confidence scale ('below about 0.95 as needing a check'). What it omits is whether the long-document path returns synchronously or hands back a job id, which matters given the polling sibling.

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 core action and output contract are front-loaded in the first sentence, and the remaining blocks are scoped to one concern each (template grammar, input modalities, instructions, long-document caveat). The template grammar block is long but each entry encodes a distinct type the agent cannot infer, so it earns its space.

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

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

There is no output schema, and the description correctly fills that gap by defining the return shape, the null convention, and the confidence interpretation. For a six-parameter tool with nested template objects, the only real hole is the async/job relationship for oversized inputs.

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 compensate entirely, and it does: every leaf type of `template` is enumerated with semantics ('verbatim-string' copied exactly, 'date' as YYYY-MM-DD, ['a','b'] pick one vs [['a','b']] pick any) and an example object is given. Each of `text`, `image`, `pdf`, and `file_path` gets a format and scope note, including the 'local server only' restriction on file_path.

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 opening line gives a specific verb and resource — 'Turn a document into JSON shaped like `template`' — plus the distinctive output property (a calibrated 0-1 confidence per field). That is enough to separate it from siblings like `get_extraction_job` or `generate_questions` 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?

It clearly states the accepted input modalities ('exactly one of: text, image, pdf, file_path') and gives concrete examples of when to supply `instructions` ('dates are day/month/year'). It does not explicitly route the agent to or away from alternatives — notably `get_extraction_job` for the long-document case it warns about — so the when-to-use picture is clear but incomplete.

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 no annotations, the description must carry the full behavioral burden. It discloses the question count, automatic language behavior, and passage length cap, but it omits the return format, failure modes, and whether the language parameter overrides the passage language.

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 front-loaded with the action and resource, then adds use cases and a key constraint. It is appropriately short with little wasted wording, though the final passage-length fragment is terse and could be integrated more cleanly.

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 generation tool with three parameters, no annotations, and no output schema, the description is incomplete. It lacks return-value shape, language-parameter behavior, and edge-case guidance, leaving the agent to infer too much about invocation and output.

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 compensate for all three parameters. It explains n and the passage length limit, but it does not explain the language parameter's semantics or accepted values, and its language statement could imply auto-detection rather than an override.

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: write natural, search-style questions that a passage answers. It adds useful qualifiers like language preservation and count, but it does not distinguish this tool from sibling tools such as detect_language or explain when generation should be chosen over them.

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 names use cases like FAQs, study cards, and search/RAG training data, which implies when the tool is useful. However, it gives no explicit when-not-to-use guidance or alternatives among the sibling tools, so the agent must infer selection criteria.

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?

No annotations are supplied, so the description carries the full behavioral burden and mostly does not. It does not disclose whether the call blocks until completion, what happens if the job is incomplete, failed, or expired, or any permission/rate-limit constraints.

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 short sentence with no padding, and the sibling reference is front-loaded. It is a dependent noun phrase rather than a full statement, which slightly weakens structure and front-loading of the action.

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 async-job result tool with no annotations and no output schema, the description should explain what is returned (status vs. extracted content) and how completion is signaled. Neither is covered, leaving the agent unable to predict the response or decide whether to poll.

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 job_id parameter, and the schema only gives a title with no type semantics beyond 'string'. The description partially compensates by stating the id comes from extract_document and has the form 'exj_...', which is genuinely useful format guidance, but nothing is said about invalid-id behavior.

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 the resource as the result of a long-document extraction job and ties it to the sibling extract_document, which aids differentiation. However, it is written as a noun fragment rather than a verb+resource statement, so what the tool actually does (fetch/retrieve) is only inferable from the tool 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?

The clause 'that extract_document left running' implies the usage context: call this after extract_document for asynchronous jobs. There is no explicit guidance on when not to call it, whether to poll repeatedly, or what to do if the job is still running or has failed.

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 no annotations, the description carries the full burden; it does disclose the core behavior (input without marks, output with marks) and demonstrates it concretely via the Yorùbá example. It does not state what happens with an unsupported or misspelled language code, whether non-target characters are preserved, or whether the operation is idempotent.

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 purpose, followed by the language list and a worked example — no filler sentences. The language list is slightly uneven, glossing yor/ibo/hau/ara but leaving the rest as bare ISO codes.

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 two-parameter text transformer with no output schema, the description covers purpose, valid language inputs, and the output shape via example. It leaves error behavior for invalid languages and any caveats about text preservation unstated, which is the main remaining 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 coverage is 0%, so the description must compensate, and it does for `language` by enumerating the accepted codes (yor, ibo, hau, vie, pol, tur, por, spa, fra, ita, ara) that the schema does not constrain via enum. `text` is only conveyed implicitly through the example, and several bare codes (vie, pol, tur) lack glosses.

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 verb+resource: "Put back diacritics, tone marks or Arabic vowel marks in text typed without them," which makes the transformation unambiguous. It does not name or differentiate itself from siblings like detect_language or extract_document, so an agent must infer the boundary itself.

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 condition for use is stated clearly ("text typed without them") and the enumerated language codes define the supported scope, which functions as a usage constraint. There are no explicit exclusions or pointers to alternative tools, 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.