Branch Docs

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

Annotations already declare this is a read-only, non-open-world, non-destructive call, so the safety profile is covered. The description adds value by disclosing the shape and scope of the response (a one-page orientation with four named sections) and by flagging that it is orientation only rather than a source of API specifics.

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, front-loaded with the invocation condition, followed by return contents, then the alternative tools. Every clause carries distinct information and nothing is repeated from the schema or annotations.

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, read-only orientation tool with no output schema, the description supplies everything needed: when to call it, what it returns, and where to go instead for detailed work. Nothing an agent needs in order to select or 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the empty schema is self-explanatory. Baseline of 4 applies for a no-parameter 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 resource (Branch orientation) and enumerates exactly what it returns: object model, worker lifecycle, two integration approaches, and environments. It also names what it is not (not a procedure or API-detail tool), so it is clearly distinguishable from search, fetch, and get-endpoint.

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?

Opens with an explicit trigger condition (user is new to Branch, asks what Branch is, how core objects relate, or where to start an integration). It also gives explicit exclusions plus the alternative tools to use for procedures and API details.

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, destructiveHint=false, and openWorldHint=false, so the agent knows the safety profile before reading the description. The description adds only the provenance of the `id` value, saying nothing about what happens on an unknown/legacy ID, error behavior, or the granularity of returned content. Useful but thin relative to what annotations already cover.

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 with no filler; the workflow dependency is placed inside the purpose statement rather than padded into a separate clause.

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 one-parameter read tool with annotations and no output schema, the definition is functional but leaves the agent guessing about the shape and scope of "detailed content" and about failure modes for invalid IDs. Those gaps are modest, but the description does no work to close them.

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 `id` property description is unusually rich (canonical project/section/slug, legacy forms, how to synthesize an ID from a link). The description only reinforces that the ID originates from `search`, which is already implied, so it stays at the baseline rather than adding meaning.

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?

"Gets detailed content for documentation by ID" gives a specific verb (gets), resource (documentation content), and a selector (ID). It also implies the contrast with the `search` sibling, which returns the IDs this tool consumes, though it never states the contrast as an explicit rule.

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 phrase "by ID returned from the `search` tool" establishes the intended two-step workflow: search first, fetch second. There are no exclusions or edge-case guidance (e.g., what to do when search returns nothing), but the positive usage 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?

The description does not contradict the annotations, which already declare this a read-only, non-destructive operation. It adds useful context about what the response includes (security schemes and servers), but it does not disclose details like authorization requirements, error behavior, or whether the endpoint details are always available.

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 a single focused sentence that front-loads the action and resource, then adds the most relevant detail about the return value. Every word contributes.

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, read-only tool with well-documented schema and annotations, the description covers the essential purpose and return contents. The only gap is the lack of an output schema and a more explicit return contract, but the tool's low complexity makes this acceptable.

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 (path and method) with clear examples, so the description adds no additional parameter-level meaning. This matches the baseline of 3 given 100% schema description coverage.

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 tool's action ('Gets detailed information') and its specific resource ('a specific API endpoint'), and even previews the key response content ('security schemes and servers'). This is distinct from list-endpoints and search-endpoints, which deal with collections rather than a single endpoint.

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 phrase 'specific API endpoint' implies the tool is meant for retrieving details about one endpoint identified by path and method, but it does not explicitly say when to use it over search-endpoints or list-endpoints. No exclusions or alternative routing are mentioned.

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 this is a safe, read-only, non-destructive operation with openWorldHint false. The description adds that results are grouped per server within an OpenAPI spec, but it does not clarify how the target spec is identified or what the response shape looks like.

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 a single focused sentence with the resource and scope front-loaded. It is efficient, though the phrase 'specific OpenAPI spec' is slightly ambiguous given that no input parameter identifies the spec.

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 read-only tool with annotations covering safety, the description is minimally adequate. However, it leaves an important ambiguity about how the 'specific OpenAPI spec' is determined and does not describe the return structure, which matters since no output schema exists.

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 has zero parameters, so there is no parameter semantics burden on the description. The baseline for zero parameters is 4, and the description does not need to compensate for schema coverage gaps.

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 and resource: it gets server variables for each server within an OpenAPI spec. This is clear enough for an agent to understand the tool's basic purpose, though it does not distinguish itself from siblings such as get-endpoint or fetch.

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 no explicit guidance on when to use this tool versus alternatives like fetch, get-endpoint, or search-endpoints. Usage is only implied by the scope of returning server variables for an OpenAPI spec.

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 and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by specifying the output organization ('organized by path') and the compatibility with get-endpoint's input, which is useful behavioral context for an agent.

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 with no redundancy. The primary function is front-loaded, and the follow-up workflow is stated efficiently without wasting words.

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, zero-parameter listing tool with annotations covering safety, the description fully explains what is returned, how it is organized, and how to proceed. Nothing essential for calling the tool 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?

The tool takes zero parameters, so the schema is trivially covered at 100%. Per the rubric, 0 params yields a baseline of 4; the description correctly omits parameter details because none exist.

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 tool lists all API paths, HTTP methods, and summaries, organized by path. This distinctively differentiates it from siblings like get-endpoint (specific endpoint) and search-endpoints (filtered lookup), leaving no ambiguity about the resource and verb.

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 clear context for using this tool as an overview before drilling into a specific endpoint, and explicitly notes that results can be passed to get-endpoint. It does not explicitly exclude alternatives like search-endpoints, but the 'all paths' phrasing implies exhaustive listing as the primary use 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the result is a fixed catalog of exactly 22 events, and full payload detail requires a follow-up fetch call. It does not discuss result size or ordering, but with zero parameters neither is a real risk.

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 invocation trigger and followed by the return contract and the escalation path. The middle clause enumerating example questions is slightly verbose but earns its place by covering the range of phrasings a user might use.

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, read-only catalog tool with no output schema, the description covers everything an agent needs: when to call it, that it returns all 22 events with payload fields, and which sibling tool to use for full detail. 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 tool takes no parameters, so the baseline is 4 and there is nothing for the description to compensate for. Nothing in the description misleads about inputs, and it correctly frames the tool as argument-free.

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 complete catalog of all 22 Branch webhook events with payload fields), which is concrete enough for an agent to know exactly what comes back. It also implicitly separates itself from the sibling 'fetch' tool, which is named as the way to get per-event detail.

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?

Opens with an explicit trigger condition ('Call this when the user asks about Branch webhooks, events, notifications, or callbacks') and enumerates the sub-cases it covers — which events exist, what data an event contains, which event fires during onboarding or payment. It then names the alternative (fetch with a listed doc id) and the condition that selects it.

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, destructiveHint=false, and a closed-world scope, so the safety profile is covered. The description adds the return fields (ID, title, URL), which is genuinely useful since there is no output schema, but says nothing about result limits, ranking, or pagination behavior.

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 with the action first and the return shape second; no wasted words. It is tight, though it spends its one sentence partly on return values rather than on the disambiguation the agent actually lacks.

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 one-parameter read-only search with annotations and a stated return shape, the definition is broadly adequate. It is still thin on where the scope boundary lies relative to the endpoint-specific siblings and on how many results come back, which matters for planning follow-up calls.

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% for the single query parameter, so the schema already carries the parameter documentation. The description only restates "with the given search query" and adds no syntax, matching, or formatting guidance, so baseline 3 applies.

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 gives a concrete verb and resource ("Searches through documentation") and even previews the result shape (ID, title, URL). However, it never distinguishes this tool from the sibling search-endpoints or list-endpoints, so an agent cannot tell from the text alone whether generic search also covers endpoint documentation.

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?

There is no explicit when-to-use guidance and no mention of alternatives such as search-endpoints, list-endpoints, or fetch. The agent must infer that this is the right tool for keyword lookup over docs, with no stated exclusions or conditions.

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 and destructiveHint=false, covering safety. The description adds useful behavioral context by stating that search results can be passed directly into 'get-endpoint', implying the output is compatible with that tool's input. It also mentions 'deep search' but doesn't detail pagination or rate limits; given annotation coverage, the added workflow info justifies a 4.

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, front-loaded with the core purpose, and every clause contributes value. No filler or repetition.

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 single-parameter search tool with annotations covering safety and no output schema, the description is quite complete. It states what it does, when to use it, and how results feed into 'get-endpoint'. It doesn't describe the return format in detail, but the workflow hint mitigates that. Missing explicit mention of alternatives or edge cases, but adequate for typical agent use.

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 parameter 'pattern' is documented. The description adds meaning by explaining that the pattern searches through 'paths, operations, and parameters', which goes beyond the schema's generic 'Search pattern (case-insensitive)'. This clarifies what the pattern can match, adding value.

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 tool's purpose: performing a deep search through paths, operations, and parameters to discover relevant API endpoints. It uses a specific verb ('search') and resource ('API endpoints'), and clarifies the scope of the search. However, it does not explicitly differentiate from sibling 'list-endpoints' (which likely lists all endpoints), leaving some ambiguity about when to choose this over listing.

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 clear usage context: 'Use this tool to find specific API capabilities, required parameters, or data models based on search keywords.' It also notes that results can be passed to 'get-endpoint', implying a workflow. However, it does not explicitly state when not to use it or mention alternatives like 'list-endpoints' or 'execute-request', so exclusions are absent.

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