OpenVidu Docs

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

Annotations already cover safety (readOnly/idempotent/non-destructive), yet the description adds substantial behavior: the '"truncated'/next_offset/headings' structure of a cut page, the 'version_used' field that must be surfaced, and the 'version_warning'/'version_sensitive' signals that indicate edition/product ambiguity in the index. This is real context beyond 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?

Front-loads the purpose, then layers continuation and version-handling guidance. It is long and dense for a 3-parameter tool, but nearly every sentence carries actionable instruction (truncation handling, version disclosure, edition/product caveat), so little 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?

No output schema exists, but the description explains the response fields (version_used, version_warning, version_sensitive, truncated, next_offset, headings) and covers the index's lack of edition/product awareness. An agent has everything needed to call and interpret the result.

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 product, version, and max_chars fully. The description's version guidance largely reiterates the schema's warning against inferring versions from dependencies, adding routing advice rather than new parameter semantics. 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?

The description opens with a specific verb+resource: it returns release notes/changelog pages already indexed for a version, and explicitly contrasts this with guessing a URL via search_docs or list_doc_sections. That is enough to distinguish it from every sibling 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?

It states when to use it (to avoid URL-guessing via search_docs/list_doc_sections), how to continue reading a truncated page (get_doc_page with next_offset or a heading), and names the alternative tool (resolve_openvidu_version_edition_product, plus AGENTS.md/CLAUDE.md first check) for resolving the version. Explicit alternatives and conditions are all present.

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, but the description goes well beyond them: truncation mechanics ('truncated', 'total_chars', 'next_offset'), the meaning of #anchor vs 'heading', the one-round-trip batching tradeoff, and the version-reporting contract ('version_used', 'version_warning', 'version_sensitive'). That is exactly the kind of operational context structured fields 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?

Purpose is front-loaded in the first clause and each subsequent sentence carries distinct payload (batching, anchors, truncation, versioning). It is nonetheless a dense, prose-heavy block, and the version guidance is longer than strictly needed, which keeps 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?

Even though an output schema exists, the description anticipates the agent's real failure modes: version inference from unrelated dependencies, silent truncation, and unstated edition/product assumptions. Nothing an agent needs to call this correctly or report results faithfully 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 coverage is 100% and the schema descriptions are already rich, so the baseline is 3. The description still adds non-schema constraints, notably the mutual exclusivity of 'url' and 'urls', anchor-vs-heading equivalence, and how 'offset'/'max_chars' chain across responses.

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 ('Returns the content of a page of the OpenVidu documentation (openvidu.io) for a specific version') and explicitly covers the batch variant via 'urls'. It also distinguishes itself from siblings by naming search_docs and list_doc_sections as the sources of valid URLs.

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 selection rule ('Pass exactly one of url and urls'), explains when to read only a heading section vs. dropping the anchor to read the whole page, and routes to the right siblings (list_doc_sections, search_docs, resolve_openvidu_version_edition_product). Both when-to-use and when-to-widen are covered.

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 certify read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely useful non-structured context: pricing is version-invariant and the response can be truncated ('truncated', 'next_offset', 'headings'), which an agent cannot learn from 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?

Three sentences, front-loaded with the purpose before the version caveat and truncation contract. Dense but nearly every clause carries distinct information; the final sentence is packed with field names and could be marginally tighter.

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 so, naming the truncation fields and the continuation path. Combined with annotation-covered safety semantics, an agent has everything needed to invoke 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?

Schema coverage is 100% and the single 'max_chars' param is already documented, so baseline is 3. The description goes further by explaining the consequence of the parameter (what truncation metadata appears and how to resume), which 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?

Opens with a specific verb+resource: 'Returns the content of OpenVidu's pricing page (editions, plans, cost model)'. The enumerated scope distinguishes it cleanly from siblings like get_doc_page, get_changelog, and search_docs.

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 routes the agent: when the page is cut at max_chars, pass the retrieved 'url' to get_doc_page with 'next_offset' (or a heading) to continue. It also explains why no 'version' argument exists, which preempts a wrong call against list_versions/get_doc_page.

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 (readOnly, idempotent, not destructive), and the description goes further by disclosing response-level behavior: version_used, version_warning, and per-result version_sensitive/version_note semantics, plus the admission that the index has no notion of edition or product. That is real behavioral context an agent would otherwise only discover by inspecting raw output.

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?

It is front-loaded correctly — mode behavior first, then routing, then output-handling obligations. It runs long, and the version-reporting instructions (how to phrase things to the user) drift toward prompt-engineering rather than tool documentation, but each sentence still serves correct invocation.

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, yet the description compensates fully by naming the significant response fields and what they obligate the agent to do. Combined with sibling-tool routing, an agent has everything needed to call this correctly and interpret the result.

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 schema's own parameter descriptions are extremely detailed, including the version-inference warning and the pointer to resolve_openvidu_version_edition_product. The description's 'Without arguments it returns an overview / With section it returns that section's pages' largely restates what the schema already documents, so the 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?

The description states a precise verb and resource ('Browses the indexed documentation of a version') and describes both operating modes: overview of all sections, or one section's pages with URLs. It implicitly distinguishes itself from get_doc_page by framing itself as the discovery step ('find out what exists before requesting a specific page').

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 explicit routing: use this to see what exists before calling get_doc_page, and it points at resolve_openvidu_version_edition_product for resolving the version parameter. The 'Don't guess' instruction and the fallback ('OMIT the parameter') tell the agent exactly what to do in the ambiguous 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 declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful non-obvious context: that it also returns the default version and hints where to look for the version-edition-product tuple, and clarifies a tempting but wrong inference (it does NOT determine deployment). It stops short of describing the return shape or ordering.

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 compact sentences, front-loaded with what it returns and immediately followed by the routing guidance. The exclusions run slightly dense but every clause is load-bearing.

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-param, read-only discovery tool with a fully-covered (empty) schema and clear annotations, the description answers what it returns, when to call it, and which sibling to use instead. 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?

Zero parameters, so the baseline is 4. The description sensibly explains the output's role as an input value for 'version', which is the salient semantic for a no-arg discovery tool.

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 (Lists) and resource (documentation versions plus the default), and explicitly names the sibling it is not (resolve_openvidu_version_edition_product). An agent can distinguish it from siblings 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 an explicit triggering condition ("Use it if you don't know what value to pass for 'version'") and an explicit exclusion with the correct alternative named ("It does NOT establish the user's deployment... call 'resolve_openvidu_version_edition_product'"). This is a textbook when/when-not/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 only cover the safety profile (read-only, idempotent, closed-world); the description adds substance beyond that, disclosing that the return value is a multi-step procedure including endpoint queries, fallbacks and security rules, that a credential-hiding mode exists via 'commands', and that the tool acts as the documented fallback path for pre-3.9.0 deployments that cannot self-report.

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 the first clause and every subsequent sentence carries distinct information (modes, fallbacks, security, prohibition), so little is wasted. It is nonetheless a single dense paragraph with long em-dash clauses that would scan faster if the three invocation modes were broken out.

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 zero required parameters and no output schema, the description still covers what is returned (a procedure and, optionally, commands), the conditions under which each mode applies, the security handling of credentials, and the explicit non-inference rule. Nothing an agent needs in order to call 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 coverage is 100%, so the baseline is 3, but the description meaningfully exceeds the schema: it explains that the no-argument call yields the detection procedure, that 'livekit_version' triggers version translation and is only valid for pre-3.9.0 deployments, and that 'commands' maps to Step 3 of the procedure. It adds routing and eligibility meaning the plain schema does not.

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 precise, narrow purpose in the form of the question it answers ('which OpenVidu version, edition and product does this project use?') and distinguishes itself from plain documentation lookups by describing a procedure derived from the deployment itself. It never names or contrasts with sibling tools such as list_versions or get_doc_page, so an agent must infer the boundary rather than being told it.

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 an explicit trigger ('before answering anything version-, edition- or product-dependent'), an explicit exclusion ('unless the project's AGENTS.md/CLAUDE.md already pins it'), and per-argument conditions ('only for deployments before 3.9.0', 'only once there is a deployment to ask'). It also states a hard prohibition on an alternative inference path ('never infer ... from the project's client SDK dependency versions').

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?

Very rich disclosure beyond annotations: stemming/synonym behavior, one-of query/queries constraint, pagination semantics via truncated/next_page, heading/anchor navigation, a livekit block warning that is NOT OpenVidu documentation, and version_used/version_warning/version_sensitive handling. Annotations cover readOnly/idempotent/openWorld, and the description adds substantial operational context without contradicting them.

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 purpose and search behavior well, but grows long with several distinct concerns (query/queries, truncation, headings, livekit block, version_used/warnings, edition/product caveat). Each sentence is useful, but the structure is dense and some guidance is buried mid-paragraph rather than cleanly separated.

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 five parameters, an output schema present, and a search tool with subtle version/edition behaviors, the description covers the key quirks an agent needs. It leaves some details to the output schema but fills in behavioral gaps the schema cannot express, such as version assumptions and the livekit block caveat.

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 the schema already documents parameters well. The description adds task-relevant semantics for query vs queries, truncated/next_page, heading/url anchor behavior, and the version_used/version_warning fields. That goes beyond the schema for response-driven parameters, meeting the 'high schema coverage = baseline 3' bar and exceeding it where it matters.

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 clear verb+resource ('Searches for a term in the indexed documentation') and adds scoping detail (per version, stemming and synonyms). It distinguishes itself from siblings like get_doc_page and list_doc_sections implicitly through 'search' behavior. Sibling differentiation is present but not as explicit as routing language would be.

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 guidance: 'Pass exactly one of query and queries'. Explains when to use queries (several searches at once) and gives a strong instruction to call resolve_openvidu_version_edition_product when the version is unknown. No explicit when-not-to-use or sibling alternatives, but the conditions are clear enough for the agent to act.

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