StitchAPI Docs

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

With no annotations provided, the description carries the behavioral burden; it discloses the return format (Markdown) and implies a read-only fetch operation. However, it doesn't state edge-case behavior such as requiring exactly one of url or slug, what happens when both are provided, or error handling for invalid slugs.

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 carry the entire definition with no filler; the main action and purpose are front-loaded, and the usage guidance follows directly. Every clause 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 fetch tool with no output schema, the description is nearly complete. The only notable gap is that it doesn't explicitly state that one of url or slug must be provided, despite the schema listing both as optional.

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%, but the description adds meaningful parameter semantics by explaining the provenance of url ('as returned by search_docs') and giving a concrete slug example. It also conveys that the two parameters are alternatives, a relationship the schema does not express since both are optional.

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 uses a specific verb ('Fetch'), names the resource ('full StitchAPI documentation page'), and specifies the output format (Markdown). It clearly distinguishes itself from sibling search_docs by positioning as the 'read the whole thing' escape hatch after a search hit.

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 explicitly frames when to use get_doc versus search_docs: when you need the full page rather than a search hit, and it instructs the agent to pass a url returned by search_docs or a slug. It doesn't include explicit exclusions or when-not-to-use scenarios, but the intended context is clear.

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 provided, the description carries the full burden of behavioral disclosure. It reveals that the search is hybrid BM25 + vector, returns only excerpts with deep links, and never full pages. These are meaningful behavioral traits beyond the schema. It does not mention rate limits or auth, but for a read-only search tool the key return behavior is well covered.

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 sentences with no filler. The first sentence states the action and method; the second explains return behavior and the follow-up tool. Every clause earns its place, and the most important information is front-loaded.

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 covers the essential context: what it searches, how it searches, what it returns, and what to do next. It could mention result ordering or pagination, but the direct pointer to get_doc makes the workflow complete enough for an agent to use 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?

The input schema already describes both parameters with 100% coverage (query as natural-language search query, limit with default and bounds). The description adds the semantic search context, which indirectly clarifies that the query should be phrased naturally, but it does not provide additional parameter-specific 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 states a specific action ('Search the StitchAPI documentation') with a clear method ('semantically (hybrid BM25 + vector)') and resource. It also explicitly distinguishes itself from get_doc by noting it returns excerpts and never full pages, so an agent can tell them apart without inspecting the sibling.

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 provides concrete guidance on when to use this tool versus the alternative: use search_docs for relevant sections/excerpts, then 'Follow up with get_doc to read a full page.' This clearly frames the search-then-read workflow and implicitly states when not to use it (when full pages are needed).

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