RideDesk Developer Docs

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that output is markdown, a useful format hint, but does not disclose error behavior, rate limits, or what happens if the topic is invalid. Given annotations, this is adequate but not rich.

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 one sentence, but it includes a long list of topics that could be trimmed or replaced with a pointer to list_docs. It is efficient overall and gets the core message across.

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, so the description should explain the return format more thoroughly. It mentions 'as markdown' but does not describe the structure or the optional host parameter's effect. It also fails to guide the agent on discovering valid topics via list_docs, leaving some gaps for a simple tool.

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%, with clear descriptions for both host and topic, and an enum for topic. The description only lists some example topics but omits 'overview' and 'endpoints', and does not mention host at all. It adds minimal value 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?

The description states the tool returns a documentation topic as markdown, which is a clear verb+resource. It lists example topics, but does not explicitly distinguish it from get_widget_snippets or get_integration_brief, so differentiation from siblings is weak.

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 explicit guidance on when to use this tool vs list_docs or search_docs. It implies you already know the topic you want, but offers no alternatives or exclusions. The description does not help the agent decide between this and sibling tools.

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 description is content-focused rather than behavior-focused. Annotations already provide readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds no additional behavioral details such as response format, pagination, or side effects.

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 entire description is a single well-structured sentence that front-loads the tool's identity and immediately explains its contents. Every phrase earns its place, with no redundant 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?

Given the simple one-optional-parameter schema, read-only annotations, and clear content description, the tool is adequately specified. A 5 would require more explicit guidance on what the returned brief looks like, but the current description is sufficient for selection.

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 input schema already fully describes the only parameter (host) with 100% coverage. The description adds no parameter-specific meaning beyond the schema, so it earns the baseline score of 3.

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 ('integration brief') and its exact purpose: 'a self-contained brief for a coding agent building a transfer-booking website on the RideDesk API'. It also lists the contained elements (flow, server-enforced rules, acceptance criteria), clearly distinguishing it from generic sibling doc-retrieval tools.

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 clear context for when to use: 'for a coding agent building a transfer-booking website on the RideDesk API'. It does not explicitly name alternatives or exclusions relative to sibling tools like get_doc or search_docs, so it stops short of a 5.

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=true, so the agent knows it is safe. The description adds 'Copy-paste tags', implying the output is raw text to embed, but does not disclose any other behavioral aspects like response format or whether output depends on the host parameter. This matches the baseline for annotation-covered tools.

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 two short sentences, lists the exact snippets, and contains zero filler. It is front-loaded with the main purpose and gets straight to the point.

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, so the description should clarify what the response contains. 'Copy-paste tags' does that broadly, but it omits any mention of the optional host parameter's role or whether the response is a single block or a list. Given the tool's simplicity and strong schema coverage, this is adequate but not complete.

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 only parameter (host) is fully described in the schema (100% coverage), so the description does not need to repeat it. However, the description does not add any extra nuance about how host affects the snippets, so it stays at the baseline.

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 clearly states it provides copy-paste tags for specific scripts and iframes (attribution, live-chat, booking/enquiry/rental widgets). This is a specific verb-resource pair and distinguishes from siblings (docs-related tools) by content. No ambiguity.

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 implies this is for embedding code, which is distinct from the sibling documentation tools, but it does not explicitly state when to use this tool over alternatives or offer any exclusions. The contrast is obvious from the content 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.

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the sequencing context ('Call first') but does not disclose any other behavioral traits such as return format, pagination, or completeness. The added context is useful but minimal, so a 3 is appropriate.

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 two short sentences, immediately stating the purpose and the recommended usage. Every word earns its place, with no fluff or redundancy. It is front-loaded with the core function.

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 list tool with no parameters and no output schema, the description adequately covers the main function and the next step. It could mention when to use search_docs as an alternative, but the 'call first' guidance provides enough context for basic usage. The annotations cover safety, so the description is 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?

With zero parameters, the description has no param details to add, and the input schema is trivial. The baseline for 0 params is 4, and the description does not mislead. It does hint that the output contains summaries, which is slightly beyond schema but not parameter-specific.

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 clearly states it lists available documentation topics with one-line summaries, using a specific verb (list) and resource (documentation topics). It distinguishes itself from siblings by positioning itself as the initial call before get_doc, making its role unique.

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 instructs 'Call first, then get_doc', providing a clear sequence of when to use this tool relative to a sibling. It implies that get_doc is for retrieving a specific topic's details, which is a useful usage guideline.

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 description states that it returns matching sections with excerpts and searches across all documentation topics, adding context beyond the readOnlyHint annotation. It does not cover pagination or rate limits, but for a simple read operation the insight is adequate.

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 exactly two sentences, front-loaded with the core purpose and followed by a useful instruction. Every sentence contributes value without unnecessary detail.

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 search tool with no output schema, the description explains the return format (matching sections with excerpts) and how to retrieve full topics via get_doc, creating a complete mental model for the agent. The readOnlyHint annotation covers safety, so nothing essential 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?

The input schema already provides full descriptions for both host and query, including concrete examples for query. The description adds no additional parameter-level detail, so the baseline of 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 clearly states the action ('Keyword search') and scope ('all documentation topics'), and distinguishes from siblings by explaining it returns excerpts and suggesting get_doc for full topics.

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 explicitly directs users to follow up with get_doc for full topics, which provides clear context for when to use an alternative. However, it does not mention when to avoid this tool in favor of other siblings like list_docs or get_integration_brief, so it excludes some guidance.

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