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

Annotations already indicate readOnlyHint=true. The description adds that it requires Infrahub 1.10+ and that a count of 0 indicates no path. No mention of performance, return format, or other behavioral traits beyond the 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?

The description is extremely concise: two short sentences plus a line about version requirement. Every sentence adds value, and the key 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?

Given 6 parameters, an output schema, and annotations, the description covers the essential behavior (shortest paths, count meaning, version dependency). It could mention that multiple paths may be returned or that path order is not guaranteed, but overall is quite 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?

Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal extra meaning (e.g., clarifying source and destination as UUID or HFID), but this is already in the schema. 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 clearly states the tool finds shortest path(s) between two nodes in the Infrahub graph, and provides a usage question as context. It is specific about the resource and action, but does not explicitly differentiate from sibling tool 'find_reachable'.

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 gives a typical use case ('how are these two objects connected?') and explains that a count of 0 means no path within max_depth. However, it does not provide explicit when-to-use or when-not-to-use guidance relative to other tools like find_reachable.

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 description does not need to restate safety. It adds version requirement (Infrahub 1.10+), but no further behavioral disclosure (e.g., performance, rate limits). Score 3 is appropriate given annotations.

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 purpose, then usage guidance. No wasted words or redundant information.

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?

Description covers core purpose and usage context. With output schema existing and annotations present, it provides sufficient guidance. Lacks mention of branch or depth parameters, but these are detailed in schema.

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 baseline is 3. Description does not add additional parameter meaning beyond schema; it only summarizes purpose.

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 finds reachable nodes of given kinds from a source node for impact analysis. It uses specific verbs and resource, and distinguishes from siblings like find_paths by focusing on reachability rather than paths.

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?

Provides explicit use case ('what depends on / is connected to this object?') and context (blast-radius, dependency discovery). Does not name alternative tools explicitly but implies when to use.

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?

Beyond the readOnlyHint annotation, the description details output formats (display labels vs. full attributes), pagination metadata (total_count, has_more), and warns about expensive queries with limit=-1.

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 well-structured, starting with purpose, then usage, filters, and pagination. Every sentence is informative with no 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?

Given the output schema exists, the description adequately covers all parameters and adds context for discovering kinds and filters, making it fully complete for effective 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?

Despite 100% schema coverage, the description adds significant value by explaining filter key patterns (e.g., name__value, rel__attr__value), include_attributes behavior, and pagination mechanics.

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 nodes of a specific kind with filtering and pagination, and explicitly distinguishes it from query_graphql by noting when to prefer 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?

The description explicitly advises preferring this over query_graphql for single-kind queries, and references get_schema for discovering kinds and filters, providing clear when-to-use guidance.

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?

Description provides detailed behavior: without kind returns catalog, with kind returns attributes/relationships/filter keys, expand controls inline peering. Aligns with readOnlyHint annotation and adds context beyond it, such as TOON-encoding and server defaults.

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 paragraphs: purpose, behavior with/without kind, and alternative. Each sentence adds information; no fluff. Could be slightly more compact but well structured.

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 presence of an output schema, the description sufficiently covers return types and edge cases (default branch, server expand setting). No gaps remain for a discovery 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?

Although schema coverage is 100%, the description adds value by explaining the effect of each parameter (e.g., kind changes the output, expand inlines peer schema) and mentions TOON-encoding for efficiency.

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 'Discover available schema kinds' and instructs to call it first when kinds or filters are unknown. It distinguishes itself from sibling tools like get_nodes by focusing on schema metadata.

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 says when to use ('call this first when you don't know what kinds or filters exist') and suggests an alternative resource (infrahub://schema) for clients that support MCP resources. Lacks explicit when-not-to-use but 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 fully discloses the read-only nature (matches readOnlyHint=true) and elaborates on the lazy creation of session branches, including the naming pattern and behavior before first write. This goes well beyond the annotation.

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 well-structured: a clear one-sentence purpose, followed by detailed behavior, typical uses, and a return specification. Every sentence adds value without extraneous text.

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?

The tool is simple (0 params, read-only) and the description covers all relevant aspects: purpose, behavior with/without session, return fields. It has an output schema but the description already lists the key names, making it fully self-contained.

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 has no parameters (0 params), so schema coverage is 100% trivially. The description adds no parameter info because none are needed. Baseline for 0 params is 4.

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 tool name 'get_session_info' is self-descriptive. The description states it returns the current MCP session state, explicitly mentioning the branch and instance address. It clearly distinguishes from sibling tools (which focus on nodes, schema, mutations) by being the only session-related tool.

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 advises calling before writes to know which branch they target, and explains when session_branch is None vs. set. It gives typical use cases. Although it does not explicitly list when not to use it, the context is clear and no alternative tool serves the same purpose.

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?

Description adds significant context beyond annotations: mutation runs on active session branch, no branch override, writes are isolated to session, changes need propose_changes for default branch, and branch/schema mutations are rejected. No contradiction with annotations (destructiveHint=true, readOnlyHint=false).

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?

Well-structured with multiple paragraphs, each adding value: purpose, comparison with siblings, branch behavior, restrictions, and pointers to related resources. No unnecessary words; 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?

Fully explains the tool's behavior, constraints, and integration with other tools (e.g., reset_session_branch, propose_changes). Output schema exists, so return values are covered. No gaps for a complex write tool with a single string parameter.

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?

Only one parameter ('query') with schema description already stating 'GraphQL mutation to execute on the active session branch.' With 100% schema coverage, the description adds little extra value beyond the param description, though it provides context on allowed mutations and suggests using get_schema for discovery.

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 executes a GraphQL mutation against Infrahub and distinguishes it from sibling tools (node_upsert, node_delete, query_graphql) by specifying its use for complex writes, relationship edits, and bulk operations not covered by typed 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?

Explicitly provides when to use (complex writes) and when to avoid (prefer node_upsert/node_delete for straightforward changes, query_graphql for reads). Names alternatives and explains branch behavior and restrictions, giving clear guidance on tool selection.

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 annotations already provide destructiveHint: true, so the description does not need to emphasize destructiveness. It adds value by explaining the session-branch behavior and the need for schema discovery, going beyond the annotations.

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 well-structured with an initial clear statement, followed by branch context, and then prerequisites. Every sentence adds value without 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?

Given the presence of an output schema and annotations, the description covers the essential context: core action, branch behavior, and prerequisite schema discovery. It could be more complete by noting the return value (though output schema may cover that) but is generally 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?

The input schema has 100% description coverage, so the baseline is 3. The description does not add significant meaning beyond the schema, except for referencing the schema resource for the kind parameter. It does not explain the difference between id and hfid.

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 'Delete a node in Infrahub on the active session branch', providing a specific verb and resource. This distinguishes it from sibling tools like get_nodes, node_upsert, and others.

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 explains that deletion applies only to the session branch and not the default branch until a proposed change is merged. It also provides guidance on discovering kinds via the schema resource or get_schema tool. However, it does not explicitly state when not to use the tool or provide direct alternatives.

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?

Disclosures beyond annotations: writes on active session branch, session branch auto-created, only scalar attributes in data, and recommends propose_changes for reviews. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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?

First sentence states purpose, followed by clear bullet points for create/update distinction and constraint on data. No filler, every sentence adds value.

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 4 parameters, output schema present, and tool complexity, description covers create/update logic, data constraints, schema discovery, session workflow, and sibling delegation. Very 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?

Schema coverage is 100%, baseline 3. Description adds value by clarifying that kind should be checked via schema resource, data should be scalar-only, and id/hfid are mutually exclusive for updates. Slightly above 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?

Description clearly states 'Create or update a node in Infrahub on the active session branch', specifying verbs and resource. Differentiates from siblings by directing relationship fields to mutate_graphql and session management to propose_changes.

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?

Explicit guidelines: omit id/hfid for creation, supply one for update; use discover schema via infrahub://schema or get_schema; use mutate_graphql for relationships; session branch and propose_changes are explained.

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 indicate not read-only, not destructive, not idempotent. The description confirms it creates a new proposed change (write operation), notes session remains active, and adds behavioral context beyond annotations.

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 concise sentences in first paragraph, second paragraph adds key behavioral detail. Front-loaded purpose statement. Every sentence earns its place with no 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?

Given output schema exists, description doesn't need return details. It covers purpose, effect, and branch behavior. Could mention error handling or permissions but not required for basic usage.

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 descriptive parameter names and descriptions. The tool description adds no extra meaning beyond what the schema already provides, so 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 it opens a proposed change (pull request) from the active session branch to the default branch, creating a CoreProposedChange for human review. It uses specific verb and resource, and distinguishes from siblings which are query/mutation 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?

The description implies usage after making changes, and states the session remains active for further modifications. It doesn't explicitly list alternatives but context clarifies it's for proposing a batch of changes for review.

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. The description adds that mutations are rejected at the AST level, which provides concrete behavioral context. However, it does not detail other potential behaviors like rate limits or caching, but for a read-only tool this is sufficient.

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 concise and well-structured: it states the purpose first, then provides usage guidelines, and ends with schema discovery references. Every sentence adds value with no 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?

The description covers purpose, when to use, alternatives, schema discovery, and the behavioral constraint (AST-level rejection of mutations). Given that an output schema exists, the tool definition is complete for an agent to select and invoke 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 description coverage is 100% (both parameters have descriptions). The description repeats that the `query` parameter is for GraphQL queries only and that `branch` defaults to None (uses default branch). It adds no new information beyond the schema, so 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 clearly states the tool's purpose: 'Execute a read-only GraphQL query against Infrahub — use for reads only, never mutations.' It specifies the verb and resource ('execute a GraphQL query') and distinguishes from mutations, including naming the sibling tool `mutate_graphql` for mutation use.

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 explicit guidance on when to use this tool vs alternatives: 'For simple attribute reads, prefer get_nodes / search_nodes — use GraphQL only when you need relationship traversal, aggregation, or fields not exposed by the typed tools.' It also explains that mutations are rejected and directs to `mutate_graphql` for mutations.

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?

Discloses behavioral traits beyond annotations: creates branches if pattern matches, rejects certain branches, affects only calling session. Annotations indicate non-read-only and non-destructive, which aligns. No contradiction.

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?

Well-structured with bullet points and clear sections. Every sentence adds value; no fluff. Appropriate length (~150 words) for the complexity.

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 tool's complexity (branch management with two modes), the description covers behavior, constraints, and automatic recovery. Output schema exists so return values are not needed.

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 already describes the parameter well (100% coverage), but description adds behavioral context like two modes and rejection rules, enhancing understanding 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 clearly states the tool resets or switches the active session branch with explicit modes (with/without branch). It distinguishes from sibling tools like get_session_info or mutate_graphql by focusing on branch management.

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?

Provides clear guidance on when to use each mode (after merging work or to switch to a named branch) and mentions constraints (rejected branch types, automatic recovery). Does not explicitly compare to siblings but gives sufficient context.

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 indicate readOnlyHint=true. Description adds that it uses Infrahub's any__value filter with partial_match=True, and explains result labeling fallback (display_label, HFID, UUID). No contradictions.

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?

Description is organized into clear paragraphs, each sentence serving a purpose. Could be slightly more concise, but front-loads the core purpose and efficiently covers usage, behavior, and alternatives.

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 output schema exists, description covers all necessary context: purpose, usage guidance, behavior, parameter semantics, and alternatives. Falls back labeling explanation is helpful. No gaps identified.

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 description adds meaning: explains query is partial substring, kind can be concrete or abstract, branch defaults to default branch, and limit has min/max constraints. These add 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?

Description clearly states it finds nodes of a specific kind by partial substring, distinguishing it from get_nodes which filters on specific attributes. It specifies the verb 'Find' and resource 'nodes', making the purpose explicit.

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 guides when to use (when only part of a value is known) and when to use get_nodes instead (for specific attribute filters). Also mentions how to discover kinds via schema resource or get_schema tool.

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