Ghosty Studio docs

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

With no annotations the description carries the full burden. It usefully discloses the return shape ('agrupadas por sección, con slug, título y descripción'), but says nothing about whether the listing is scoped, paginated, or how the locale parameter affects results.

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 dense sentence that front-loads the action and groups the output information compactly. Nothing is wasted or 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?

There is no output schema and no annotations, so the description is the only source of behavioral detail. It covers the return structure adequately but omits the locale parameter's effect and any usage routing against siblings, leaving real gaps for a tool with this much unstated context.

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% and the single 'locale' parameter is never mentioned in the description. The enum values es/en are visible in the schema, but the description does not explain what locale changes about the returned content, leaving the one parameter undocumented.

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 ('Lista todas las páginas de la documentación') plus the grouping and returned fields, so the operation is unambiguous. It does not, however, distinguish itself from the sibling search_docs, which also retrieves documentation content.

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 indication of when to use this versus search_docs or read_doc. The agent must infer that this is the exhaustive listing tool while search_docs is for queries, and no such routing guidance is given.

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 behavioral burden. It usefully discloses the spec version and output format (OpenAPI 3.1, YAML), which goes beyond a bare name. However, it says nothing about response size, whether the spec is complete or filtered, auth requirements, or caching behavior for a potentially large payload.

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 front-loaded sentence that leads with the action and resource. Every clause earns its place; no filler or redundancy.

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 tool with no output schema, the description covers what is returned and in what format, which is the essential information. It stops just short of noting scale or that the spec covers the entire public API surface, but nothing critical to correct invocation 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 tool takes zero parameters, which is the baseline-4 case. There is nothing for the description to disambiguate, and it correctly implies a parameterless fetch of the whole specification.

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 verb (Devuelve / returns) and a precise resource (OpenAPI 3.1 specification of Ghosty Studio's public API), plus the serialization format (YAML). This is clearly distinguishable from the sibling documentation tools (list_docs, read_doc, search_docs), which serve a different purpose.

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 says what the tool returns but never states when to call it, what question it answers (e.g. client generation, endpoint discovery), or how it relates to the docs siblings. Usage can only be inferred from the resource name.

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 behavioral burden; it does disclose the return format (full page, markdown), which is genuinely useful. However it says nothing about failure behavior for an unknown slug, pagination/truncation, or how locale affects the result.

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 front-loaded sentence: verb, resource, format, then the addressing key with illustrative examples. No filler and nothing that fails to earn 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 low-complexity two-parameter read tool with no output schema, the description covers the core (what is returned and how it is addressed) but omits locale semantics and any error/not-found behavior, leaving the agent to guess at those aspects.

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 adds real meaning for slug by giving concrete format examples («api/autenticacion», «configurar»), but the second parameter, locale (with its enum), is never mentioned and its default/effect is left undocumented.

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 (devuelve), resource (una página completa de la documentación), output format (markdown) and addressing key (por su slug). This cleanly distinguishes it from list_docs/search_docs by implying single-document retrieval, though it never names a sibling explicitly.

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: the slug-addressing scheme signals 'use this when you already know the exact slug,' which implicitly routes users without a slug toward search_docs or list_docs. There is no explicit when-to-use vs. the three siblings and no stated prerequisites.

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 behavioral burden and discloses useful traits: the search is lexical (not semantic), returns up to 8 pages, and lists the exact fields returned. It omits authentication, rate limits, or ranking details, but the core behavior is transparent.

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 concise sentences with zero waste, front-loading the purpose, then the return shape, then the usage hint. Every sentence 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 simple two-parameter search tool with no output schema, the description adequately explains what it does and what it returns. It could mention pagination or locale behavior, but it is complete enough for correct invocation.

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 input schema already documents both parameters (query and locale). The description adds no additional meaning beyond the schema, making the baseline 3 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 in Ghosty Studio documentation, with a clear scope (lexical search by title, headings, and text). It distinguishes itself from read_doc by recommending use before it, but does not explicitly differentiate from list_docs or openapi.

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 says to use it before read_doc, giving a clear usage context. However, it does not state when not to use it or mention alternatives like list_docs.

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