Coding agents in multi-service codebases routinely rebuild existing helpers, trust stale type definitions, and modify API contracts without knowing who consumes them.
Carrick solves this by indexing your entire TypeScript ecosystem across service and repository boundaries. By integrating deeply with the TypeScript compiler, Carrick traces every route, type, and cross-service call while recording function behaviour so agents search by intent rather than name.
Delivered via MCP for AI agents and LSP for IDEs, Carrick ensures models see existing endpoints and utilities before generating new code. The scanner is source-available and runs from your CLI or CI pipeline.
Scored across 17 tools
The topology and contract tools (get_project_map, get_service_graph, list_services, get_operation, check_compatibility, get_contract_pair) clearly overlap in scope, but each description explicitly cross-references its neighbours and states when to prefer which tool. The agent is given strong guidance ("use X first", "for Y use Z"), so boundaries are mostly learnable despite the layered surface.
All tools use snake_case with a consistent verb prefix: get_*, list_*, check_*, find_*, search_* plus one bare action (scaffold). The pairing of get_/list_ for retrieval and find_/search_/check_ for queries is predictable and readable.
17 tools is on the heavier side but each maps to a distinct layer of a code-intelligence domain (topology, contracts, types, dependencies, functions, scaffolding). Nothing feels obviously redundant, though the graph/map/operation trio pushes toward the upper bound.
The surface covers topology, contract checking, type resolution, dependencies, function intents, callers, external calls, and onboarding scaffolding — a broad lifecycle for the domain. Minor gaps exist (no direct callee lookup; callers are treated as measured-with-caveats), but core investigative workflows are supported.
Check a consumer service's calls against a producer's operations: missing or unused operations, plus stored type verdicts (coverage in type_verdicts). Read status first. It reads compatible, incompatible, partially_checked, or unresolved where nothing was compared, and pairs_compared and pairs_uncompared say how much of the pair the check reached. Call it before removing or changing any route, shape, field, or event. Consumers that reach the producer through a published SDK package have no call site of their own and are listed separately in via_sdk, never merged into the direct pairs. For whole-project topology, use get_service_graph first. To read both sides' types for the operations a verdict names, use get_contract_pair. Reference: https://docs.carrick.tools/mcp-tools
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Filter by HTTP path, GraphQL field, or socket event name. A `{field=value}` dispatch suffix narrows to one case. On a large pair this is what narrows the answer; paging alone cannot. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| limit | No | Issue rows per page (default 50, max 200). Errors come first; issue_counts counts every category. A page is cut further when the response would be too long to read inline. | |
| method | No | Filter by operation label: HTTP method (GET, POST), GraphQL kind (QUERY, MUTATION), or socket direction (CLIENT->SERVER, SERVER->CLIENT, UNKNOWN). UNKNOWN also selects HTTP routes whose verb the scan could not read; each row names its protocol. | |
| offset | No | Issue rows to skip (default 0). Pass the `next_offset` from a previous call to page through. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| consumer_service | Yes | The service making API calls | |
| producer_service | Yes | The service exposing endpoints |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior the annotations cannot: the possible status values (compatible, incompatible, partially_checked, unresolved) and what each means, how pairs_compared/pairs_uncompared quantify coverage, and the important caveat that SDK-mediated consumers appear in via_sdk and are never merged into direct pairs.
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?
It is front-loaded with the core action, then layers status semantics before the routing guidance. It is denser than most definitions but each sentence carries load; the split across response semantics and sibling routing is efficient rather than 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?
With no output schema, the description must convey return semantics, and it does: verdict categories, pair coverage counters, and the via_sdk exception. It also cites a reference URL for deeper documentation, so an agent has everything needed to call and interpret the 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 description coverage is 100%, so the schema already documents all 8 parameters including path, method, limit/offset paging, and project resolution. The description adds usage semantics for the response fields (status, pairs_compared, pairs_uncompared, via_sdk) but nothing about parameter syntax or formats beyond what the schema provides.
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 verb and resource ('Check a consumer service's calls against a producer's operations') and enumerates the verdict categories it produces (missing/unused operations, stored type verdicts). An agent can distinguish it from data-retrieval siblings like get_callers or get_operation immediately.
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 an explicit precondition ('Call it before removing or changing any route, shape, field, or event') and routes to named alternatives with conditions: get_service_graph for whole-project topology first, get_contract_pair for reading both sides' types. When-to-use, ordering, and alternatives are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find functions that already do what you are about to write, and places this project has built the same thing twice. Pass functions with one entry per new or edited function (name and file when it is already indexed, one plain sentence when it is not) and each entry comes back with the closest functions in other files. Omit functions for a whole-project audit that groups the functions describing the same behaviour. Matching reads how the index describes a function rather than its body, and every row carries the file and line span of the function it names. For one concept rather than a set of functions, use search_by_intent.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Audit only: compare the functions under this repo-relative directory or file prefix, matched on whole segments (`lib` covers `lib/a.ts`, never `library/a.ts`). In a monorepo the service's directory is part of the path. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| limit | No | Ceiling on groups per page in the audit mode (default 20, max 50). A page is cut to what one response holds, so it can come back shorter; `clusters_note` states what this page holds and `next_offset` continues it. | |
| top_k | No | Matches per entry in the targeted mode (default 5). | |
| offset | No | Groups to skip in the audit mode (default 0). Pass the `next_offset` from a previous call to page through. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | No | Limit the comparison to one service (fuzzy match by service name, repo name, or trailing segment). | |
| functions | No | One entry per function to check, up to 20 in a call. Omit for a whole-project audit. | |
| min_lines | No | Shortest function to compare (audit default 3, targeted default 1). One-line and two-line wrappers carry no behaviour to reuse; the response says how many rows this hid. | |
| scan_from | No | Audit only: where the next window starts. An audit larger than one call compares the functions in windows and each answer names its `window`; pass its `next_scan_from` to continue. | |
| include_tests | No | Include test files, which repeat each other by design (default false). | |
| include_callbacks | No | Include the anonymous callbacks the scan indexed, such as a `map_handler` row (default false). They cannot be imported, so a group of them is not a reuse finding. | |
| include_generated | No | Include generated and bundled files (default false). | |
| similarity_threshold | No | Floor for a match. Defaults to 0.85 between two indexed functions and 0.45 for a `description`, which are different scales: one side is a stored vector and the other a sentence embedded on the spot. The answer carries `vector_basis` for which stored vectors it compared, and its hint says what that basis means for a renamed copy. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description's added value is the matching basis ('reads how the index describes a function rather than its body'), pagination continuation (`clusters_note`, `next_offset`, `window`, `next_scan_from`), and that pages can come back shorter. It does not address error behavior, ambiguity handling beyond the schema, or rate limits, so not a full 5.
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?
Front-loaded with purpose and mode selection in the first two sentences, with the sibling pointer last. Dense and mostly waste-free, though the middle sentence packs matching semantics and return-row structure together, making it slightly heavy.
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 14-parameter tool with no output schema, the description covers the two operating modes, pagination tokens, and matching semantics adequately, and the 100% schema coverage carries the parameter detail. It leaves the shape of a returned match group only partly described, which keeps it short of 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 the schema already documents all 14 parameters thoroughly. The description restates the `functions` entry shape and mode defaults (top_k 5, audit 20) but adds little meaning beyond what the parameter descriptions already provide, so the baseline of 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?
States a specific verb and resource ('Find functions that already do what you are about to write') and adds the second use case (duplicate detection across the project). It explicitly distinguishes itself from the sibling search_by_intent by scope ('one concept rather than a set of functions').
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?
Names both invocation modes and the condition that selects each: pass `functions` for targeted per-function lookup, omit it for a whole-project audit. It also names the alternative tool (search_by_intent) and the condition under which it is the right one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the operations one service exposes: HTTP endpoints, GraphQL fields, socket events. Call it when unsure which operations a service has or whether one exists. For the types of a known endpoint, use get_endpoint_types. When you already know the operation and need its producer or its consumers, use get_operation.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| method | No | Filter by operation label: HTTP method (GET, POST), GraphQL kind (QUERY, MUTATION, SUBSCRIPTION), or socket direction (CLIENT->SERVER, SERVER->CLIENT, UNKNOWN). UNKNOWN also selects HTTP routes whose verb the scan could not read; each row names its protocol. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | Yes | Service name to look up (fuzzy match by repo name, service name, or trailing segment) | |
| path_contains | No | Filter operations whose path, field, or event name contains this substring |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the multi-protocol scope (HTTP/GraphQL/socket), which is contextual rather than behavioral; it says nothing about result volume, pagination, or truncation on a service with many operations. With annotations carrying the behavioral burden, 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?
Three sentences, each doing distinct work: purpose with scope, entry condition, then two explicit routing alternatives. Front-loaded with the purpose and free of restated name/title 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?
There is no output schema, so the description is the only place return shape could be signaled; it names the protocol kinds but not what a row contains or how large a result set can get. Otherwise it is complete for a read-only, filtered listing tool whose annotations already cover safety. Minor gap keeps it just short of 5.
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% and all five parameters carry substantive descriptions (repo resolution, method label semantics including the UNKNOWN case, service fuzzy match, path_contains substring). The description adds no parameter-level meaning beyond that, so the 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?
States a specific verb and resource (list the operations one service exposes) and enumerates the exact scope it covers: HTTP endpoints, GraphQL fields, socket events. That enumeration lets an agent distinguish it from sibling listers like get_endpoint_types or get_operation without opening a schema.
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?
Gives an explicit trigger ('call it when unsure which operations a service has or whether one exists') and then routes to two named alternatives with the condition that selects each: get_endpoint_types for types of a known endpoint, get_operation for producer/consumers of a known operation. This is a complete when-to-use / when-not-to-use map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recorded direct callers of a named function, with their service, file and line span. Zero recorded callers is not safe-deletion evidence; callback and value references are unmeasured. Call it before changing or removing a function to see what a signature change would break; pass depth for transitive callers. Rows name the enclosing caller, not the call-site line. For what a function calls rather than who calls it, use list_function_intents.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Path suffix of the file the TARGET is defined in (e.g. `src/auth/session.ts` or `session.ts`). Use it when the name matches definitions in more than one file. | |
| name | No | Alias for `function_name`, spelled the way the returned rows spell it. Pass one or the other. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| depth | No | How many call levels to walk back (default 1, max 3). Above 1, each row carries the chain from that caller to the target. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| function_name | No | Function to find callers of. Class members are indexed as `Class.member`; a bare member name matches the part after the dot, and the options are listed back when it is ambiguous. Pass this or its alias `name`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real caveats: zero results are not proof of safety, callback and value references are unmeasured, and rows name the enclosing caller rather than the call-site line. These limitations materially affect how an agent should interpret output, though pagination/limits are not addressed.
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?
Four tight sentences, front-loaded with the core action and return shape, then caveats, then the routing pointer. No filler; each clause carries distinct 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?
With no output schema, the description compensates by describing row composition (caller, service, file, line span, and chained rows at depth>1). Combined with the caveats and sibling pointer, an agent has enough to select and call 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?
Schema coverage is 100% and the schema descriptions are thorough (aliases, project resolution, ambiguity handling), so the schema does the heavy lifting. The description only restates that `depth` yields transitive callers, adding relational context but little beyond the schema's own 'how many call levels to walk back' note.
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 ('List recorded direct callers of a named function') plus the returned fields (service, file, line span). It explicitly routes to the sibling `list_function_intents` for the inverse question, so an agent can distinguish it without opening a schema.
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?
Gives concrete when-to-use ('Call it before changing or removing a function to see what a signature change would break'), an explicit when-not (zero callers is not safe-deletion evidence), and names the alternative sibling for the opposite direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put one consumer and one producer side by side, operation by operation: the producer's request and response types, every consumer call site with the type that call site expects, and the type verdict the scan stored, with its scanner version. Call it when you are about to change a shape and need to know what the other side already believes it is, or when a compatibility verdict names a problem you cannot place. It reports what the index holds and adds no verdict of its own. It shows HTTP operations side by side, and only the operations a consumer call wins onto; for GraphQL, socket and pub/sub pairs, check_compatibility carries the stored verdicts. For the producer's types alone, use get_endpoint_types; for which calls match at all and which do not, use check_compatibility. Reference: https://docs.carrick.tools/mcp-tools
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Narrow to one route path as indexed (e.g. /api/users/:id). A `{field=value}` dispatch suffix, as the listings print it, narrows to that case. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| limit | No | Operations per page (default 10, max 50). Ranked by consumer call-site count, then by untyped sides. | |
| method | No | Narrow to one HTTP method (GET, POST, PUT, DELETE). | |
| offset | No | Operations to skip (default 0). Pass the `next_offset` from a previous call to page through. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| consumer_service | Yes | The service making the calls | |
| producer_service | Yes | The service serving the operations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/no-destructive, so safety is covered. The description adds real behavioral context beyond that: it 'reports what the index holds and adds no verdict of its own,' and it is limited to HTTP operations that a consumer call wins onto — both meaningful scope disclosures. It stops short of describing pagination mechanics, though the schema covers those.
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?
Front-loaded with the core action and its outputs, then usage triggers, then routing alternatives, then a reference URL. Dense but each sentence does work; the parenthetical enumeration of returned fields is slightly listy but earns its place given there is no output schema.
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?
With no output schema, an 8-parameter surface, and reach into sibling routing, the description compensates well: it enumerates what is returned (producer request/response types, consumer call sites with expected types, stored verdict plus scanner version) and maps the tool against its nearest siblings. Nothing an agent needs to call 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?
Schema description coverage is 100% (path, repo, limit, offset, project, method, service fields all documented, including the dispatch-suffix nuance), so the schema carries the parameter burden. The description adds no syntax or format detail beyond it, so the 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?
Specific verb ('put side by side, operation by operation') plus resource (consumer/producer pair) plus scope (HTTP operations, stored type verdicts with scanner version). It explicitly distinguishes itself from get_endpoint_types ('producer's types alone') and check_compatibility ('which calls match at all'), so an agent can route without inspecting schemas.
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?
Gives two concrete triggering situations ('about to change a shape', 'a compatibility verdict names a problem you cannot place') and explicit exclusions: GraphQL/socket/pub-sub pairs go to check_compatibility, producer-only types go to get_endpoint_types, matching goes to check_compatibility. When/when-not/alternatives are all covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the extracted TypeScript request/response types for one endpoint instead of guessing from sample JSON. Call it before building a request body or parsing a response. For nested types, follow with get_type_definition. To read these types against the type each consumer call site expects, use get_contract_pair. Reference: https://docs.carrick.tools/mcp-tools
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | API path (e.g. /api/users/:id), GraphQL field, or socket event name. A `{field=value}` dispatch suffix, as the listings print it, names one case of a dispatching route; a case whose handler is declared at its own site returns the rows at that site, and cases that share a handler return the route's rows. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| method | Yes | HTTP method (GET, POST, PUT, DELETE) — or, for a non-HTTP operation, its label from get_api_endpoints (QUERY, MUTATION, CLIENT->SERVER). UNKNOWN names both a socket row whose direction the scan could not read and an HTTP route whose verb it could not read; type text answers the HTTP route and the socket row gets the redirect. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | Yes | Service name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered by structured data. The description's only behavioral addition is provenance — the types are *extracted* rather than inferred from sample JSON — which is genuinely useful, but it says nothing about failure cases (missing endpoint, unresolved project), caching, or what the type text 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?
Three sentences, front-loaded with the primary action and rationale, then two alternative-routing sentences, then a reference link. Every sentence earns its place with no padding.
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 read-only lookup with no output schema, the description correctly conveys what comes back (TypeScript request/response types for one endpoint) and where to go next. It is slightly thin on the shape/limits of the returned type text and on what happens when no types were extracted, but the essentials for correct invocation are present.
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%, and the parameter descriptions are unusually rich (dispatch-suffix semantics, UNKNOWN handling, repo/project resolution), so the schema carries the parameter burden entirely. The tool description adds no parameter-level guidance, which is the expected baseline when the schema is this complete.
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 ('Read the extracted TypeScript request/response types for one endpoint') and immediately distinguishes itself from sibling tools get_type_definition and get_contract_pair. The scope and rationale ('instead of guessing from sample JSON') make its job unmistakable.
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 names the trigger ('Call it before building a request body or parsing a response') and routes two adjacent needs to alternatives: get_type_definition for nested types, get_contract_pair for checking against consumer call-site expectations. Nothing about when to pick this over siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the findings list on main: type mismatches between endpoints and their callers, and groups of functions that look like copies of each other, built after each scan of main. Each row carries every place as file and line, what to check, and the call that drills into it. get_project_map shows the first rows under FOUND ON MAIN; this tool lists them all, paged.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | One kind of finding: "type_mismatch" or "similar_functions". Omit for every kind. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| limit | No | Findings per page (default 20, max 100). A page is cut to what one response holds. | |
| offset | No | Findings to skip (default 0). Pass the offset the previous page's last line names to continue. | |
| status | No | "open" (default) for the findings on main now, "fixed" for the ones a later scan of main no longer found. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real context: results are 'built after each scan of main', output is paged, and each row carries file/line locations plus a drill-in call. It does not spell out page-size/continuation mechanics beyond the word 'paged'.
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, both dense with load-bearing content and no filler; the scope statement and the sibling comparison are front-loaded. The prose is telegraphic in places ('what to check'), which costs a little readability but no wasted sentences.
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?
With no output schema, the description compensates by describing row contents (every place as file and line, what to check, the drill-in call), freshness, and pagination. Combined with full schema coverage and safety annotations, an agent has what it needs; only finer paging details are absent.
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 all six parameters including both enums (kind, status) and pagination limits are already documented. The description only gestures at paging and adds no syntax or semantics beyond the schema, so the 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?
Names a specific verb and resource ('Read the findings list on main') and immediately enumerates the two finding kinds it returns, type mismatches between endpoints/callers and near-duplicate function groups. It also differentiates itself from the sibling get_project_map, so an agent can distinguish it without opening either schema.
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 routes between siblings: 'get_project_map shows the first rows under FOUND ON MAIN; this tool lists them all, paged.' That tells the agent which tool to pick and when. It stops short of stating exclusions (e.g., when a narrower tool like find_similar or get_contract_pair is preferable for a single finding).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start here when you know an operation but not the service: given a method and a path, it returns every service that serves it, every call site that reaches it, and the recorded calls that resolved to no producer, with a file and line on each. Use it before changing or removing a route to see the blast radius, and to answer "who serves this" without guessing a service first. Every response also names what the index holds one method or one path segment away, so a call recorded under a neighbouring method or path version cannot read as a confident zero. Bounded to one operation; for the whole topology use get_service_graph, for request/response types get_endpoint_types. Reference: https://docs.carrick.tools/mcp-tools
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Route path (e.g. /api/users/:id — `:id`, `{id}` and `${expr}` all resolve), GraphQL field, socket event, or pub/sub topic. A `{field=value}` dispatch suffix, as the listings print it, narrows the producers to that case. Host-free: internal operations are indexed by route path, not by URL. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| method | Yes | HTTP method (GET, POST, PUT, DELETE) — or, for a non-HTTP operation, its label from get_api_endpoints (QUERY, MUTATION, CLIENT->SERVER, PUBSUB). UNKNOWN names both a socket row whose direction the scan could not read and an HTTP route whose verb it could not read; each returned row names its protocol. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | No | Narrow the CALL-SITE sections (consumers, unmatched calls, consumer-side near misses) to one service. Producers are always project-wide. Use it to cut a hub operation's consumer list down, not to find the producer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations by disclosing the exact return shape (producers, call sites, unmatched calls, each with file and line), a subtle near-miss guarantee about neighbouring methods and path versions, and the scoping limit of one operation. This is meaningful behavioral context the annotations cannot convey.
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?
Front-loads the core usage condition and the return summary, then layers in the near-miss caveat and sibling routing. Every sentence carries information, though it runs dense and long enough that a small trim would help.
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?
With no output schema, the description carries the return-value burden and does so completely: producers, call sites, unmatched calls, file/line locations, near-miss disclosure, and one-operation bounds. Nothing an agent needs before calling 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?
Schema description coverage is 100%, so method, path, repo, project, and service narrowing are already documented in the schema, including the service-narrows-call-sites detail. The description only restates "a method and a path" and adds no syntax or format guidance beyond the schema, so the baseline of 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?
States a specific verb and resource — given a method and path, return every service that serves it plus call sites — and explicitly distinguishes itself from siblings get_service_graph and get_endpoint_types. An agent can identify the tool and its boundary without opening any schema.
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 when to reach for it ("Start here when you know an operation but not the service", "Use it before changing or removing a route to see the blast radius") and routes elsewhere for adjacent needs (whole topology → get_service_graph, request/response types → get_endpoint_types).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this first in a session: a compact plain-text map of the project, naming the sibling services this project indexes, the contracts this repo depends on, who consumes this repo, and the unmatched calls with how many of them match no route, with the drill-down tool at the end of every section. Cheap; pass service to split THIS REPO from its siblings, detail for more rows per section.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| detail | No | Raise the per-section row caps roughly fivefold. Use it when the default map collapsed a section you need to read. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | No | Your repo or service, so the map splits THIS REPO from the siblings you do not have checked out (fuzzy match by service name, repo name, or trailing segment). Omit on a single-service project; omit on a multi-service one to render the whole project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that: output is compact plain-text, it is cheap, every section ends with a drill-down tool, and it is meant to be the first call in a session.
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?
Front-loaded with the highest-value instruction ('Call this first in a session') and every clause carries information about output content or parameter use. It is a single dense run-on sentence, which makes it slightly harder to scan than it needs to be.
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 carries the burden of describing returns — and it does, listing the four section types and the drill-down affordance. It stops short of naming those drill-down tools or noting size/pagination behavior, but is otherwise sufficient for a zero-required-param, read-only 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 description coverage is 100%, so the schema already explains repo, project, detail, and service with the same 'when to use it' framing. The description restates the service split and detail row caps without adding syntax, defaults, or format detail the schema lacks, so the 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?
States a specific verb+resource ('map of the project') and enumerates exactly what the map contains: sibling services, contracts depended on, consumers, unmatched calls. This distinguishes it from siblings like get_service_graph and get_service_dependencies, which cover overlapping-but-different slices.
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?
Gives a clear entry-point rule ('Call this first in a session') and conditions for the two optional params (split THIS REPO from siblings; more rows when a section collapsed). It does not name the alternative tools an agent might use instead, so it falls short of full when/when-not/alternatives coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read npm dependencies: one service's full package list, or org-wide conflicts when called without a service. Conflicts are graded on the semver ranges written in package.json, not on version strings: a package is listed only when no single install satisfies every service's range; error means the ranges span different majors, warning means they miss within one major. Each conflict carries a one-sentence summary naming the groups. Call it before adding or bumping a package.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | No | Service name (omit for org-wide conflict analysis) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive) and the description goes well beyond them: it explains that conflicts are graded on semver ranges rather than version strings, defines what error vs warning mean, and notes each conflict carries a one-sentence summary. Since no output schema exists, this semantic detail is valuable for interpreting 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?
Front-loaded with the purpose before the mode distinction and the grading semantics. It is dense but almost every sentence carries information; only the semver-range restatement is slightly redundant.
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?
With no output schema, the description carries the burden of explaining returns, and it does so adequately for the conflict mode (grading, error/warning, summary field). The single-service package-list shape is left less specified, but nothing critical for 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?
Schema coverage is 100% and all three parameters are documented there. The description restates the key behavioral distinction (omitting service yields org-wide analysis) but adds no syntax or format detail beyond the schema, so the baseline of 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?
States a specific verb and resource (read npm dependencies) and clearly enumerates its two modes: one service's package list, or org-wide conflicts when service is omitted. It is not explicitly differentiated from related siblings like check_compatibility or get_service_graph, which keeps it just below a 5.
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?
Gives a concrete trigger: "Call it before adding or bumping a package." It also states the condition that selects org-wide mode (omit the service). No explicit when-not or named alternative is given, so it falls 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.
Return the whole cross-service call graph in one call: consumer -> producer edges across every protocol, unmatched calls, orphaned endpoints. Use it first for topology: who depends on a service, what a change ripples into. An edge carrying via_sdk reaches its producer through a published package rather than a call site of its own. An edge carrying same_service has one service at both ends, a service calling its own operation, and is listed after the cross-service ones. For one pair in depth, use check_compatibility. For the types on both sides of one pair's operations, use get_contract_pair. On a large project, call get_project_map first: it summarises this graph section by section and names the drill-down tool for each.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| limit | No | Rows per array per page (default 40, max 200). The *_count totals are never paged. | |
| offset | No | Rows to skip in every array (default 0). Pass the `next_offset` from a previous call to page through. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | No | Optional: return only edges that TOUCH this service (as consumer or producer), plus its unmatched calls and orphaned endpoints. Omit for the whole project graph. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real semantics beyond them: what via_sdk means, what same_service means and how those edges are ordered. It does not cover paging behaviour or response size expectations, which is the remaining gap.
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?
Front-loaded with the core action, then edge-type semantics, then routing. Every sentence earns its place, though the via_sdk/same_service explanations are dense and the paragraph is longer than strictly needed.
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?
With no output schema, the description carries the burden of explaining what comes back and it does: edge shapes, unmatched calls, orphaned endpoints, edge ordering. Combined with full schema coverage of the five optional params, an agent has everything needed to call 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?
Schema description coverage is 100%, so every parameter including service scoping, limit/offset paging and repo/project resolution is already documented. The description implies service-scoped queries ('who depends on a service') but adds no syntax or behaviour beyond the schema. 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?
States a specific verb and resource ('Return the whole cross-service call graph') and enumerates exactly what the payload contains: consumer -> producer edges, unmatched calls, orphaned endpoints. This is distinguishable from every sibling at a glance.
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 when to use it ('Use it first for topology'), and routes to named alternatives with the condition that selects each: check_compatibility for one pair in depth, get_contract_pair for types on a pair, get_project_map first on a large project. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the fully resolved TypeScript definition of a named type, with transitive dependencies. Call it after get_endpoint_types when a type references nested types you need expanded. Accepts the Endpoint_ alias or a real symbol name.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | Yes | Service name | |
| type_alias | Yes | Either the synthetic type alias (Endpoint_<hash>_Request|Response, optionally suffixed _Call<id> on consumer entries; from get_endpoint_types results) or the real exported symbol name (e.g. Order, as shown by search_by_intent and function signatures) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description adds real behavioral context beyond them: the resolution is recursive ('transitive dependencies') and the alias input is flexible. It still doesn't say anything about output size, depth limits, or resolution failure 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?
Three tight sentences with the core purpose front-loaded and the sequencing hint last. Every sentence earns its place; nothing is padded, though it is a touch terse on output expectations.
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 read-only, no-output-schema resolver, the description conveys what is returned (resolved definition plus transitive deps) and when to call it. It leaves minor gaps around result shape and depth, but nothing that would prevent 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 all four parameters (including repo/project auto-resolution and the alias format) are already documented in the schema. The description's mention of accepted alias forms duplicates the schema rather than adding syntax or format detail, 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?
States a specific verb and resource ('fully resolved TypeScript definition of a named type') plus a distinguishing scope note ('with transitive dependencies'). An agent can differentiate it from get_endpoint_types, which is explicitly referenced as the shallow-input counterpart.
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?
Gives an explicit triggering condition and ordering ('Call it after get_endpoint_types when a type references nested types you need expanded'), which is strong sequencing guidance. It does not state when not to use it or name an alternative expansion tool, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enumerate this project's recorded outbound-call candidates: SDK calls into declared dependencies, calls to declared external domains, and env-var URL bases, each with its service, file and line. Use it to inventory or audit what a service talks to outside itself; for an audit, start with view "targets" to see every distinct target with counts, then fetch call sites per target. Rows are candidates, not verified egress.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| view | No | "targets" returns one row per distinct (target, mechanism) with call-site counts, services, and sample operations instead of raw call sites. The audit entry point: read the targets first, then drill into each with the `target` filter. | |
| limit | No | Max rows per page (default 100, max 500). | |
| offset | No | Row offset into the inventory (default 0). Pass the `next_offset` from a previous call to page through. | |
| target | No | Case-insensitive substring of the target — the dependency name, hostname, or env-var name. Use it to narrow past framework and utility packages. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | No | Filter to one service (fuzzy match by service name, repo name, or trailing segment). Omit for the whole project. | |
| mechanism | No | Filter by how the call was recorded: sdk (a call into a declared dependency), external_http (a declared external domain), env_var_url (a declared external env-var base). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/no-open-world. The description adds real value beyond them: 'Rows are candidates, not verified egress' warns about data trustworthiness, and it describes the paging mechanism (next_offset). It does not cover result-size or rate behaviors.
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 enumeration scope before the usage/workflow guidance; every clause carries information. It is dense with comma-separated lists, slightly reducing scanability.
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?
With no output schema, the description correctly specifies returned fields (service, file, line) and paging via next_offset, and the candidate caveat. Minor gaps remain, e.g. whether a total count or has-more indicator accompanies next_offset.
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 schema already documents repo, view, limit, offset, target, project, service, and mechanism. The description mostly restates the three mechanism categories and the targets view; the only marginal addition is advice to use target to narrow past framework/utility packages.
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 (Enumerate) and resource (outbound-call candidates) and enumerates the three recorded categories — SDK calls, external domains, env-var URL bases — plus the returned fields (service, file, line). An agent can tell this apart from inventory/audit siblings like get_service_dependencies.
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 frames the use case (inventory or audit what a service talks to outside itself) and prescribes a workflow: start with view="targets", then fetch call sites per target. It does not name which sibling to avoid or when not to use it, so it falls 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.
List indexed functions with their one-line intents, paginated; filter by service or substring. The index covers every function with an intent, not just exported ones. Use it to browse what a service contains or compare what sibling repos have built. Pass file to answer "what can I call in this file" without reading it, with compact for signature-only rows. For concept queries ('dedupe users by email'), use search_by_intent instead.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Path suffix of the file to list functions from (e.g. `src/oauth2/service.ts` or `service.ts`). Matched on whole segments, so `gin.ts` never matches `login.ts`. | |
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| limit | No | Max functions per page (default 50, max 200). The full org haystack is too large to return inline. | |
| offset | No | Number of functions to skip before this page (default 0). Pass the `next_offset` from a previous call to page through. | |
| compact | No | Return signature-only rows (name, signature, line span, first sentence of the intent) instead of full detail. Use it with `file` to read what a file offers at a fraction of the source. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| service | No | Filter to a specific service (omit for all services) | |
| typed_only | No | When true, return only functions whose signature is fully explicit (every param and the return annotated). | |
| name_contains | No | Case-insensitive substring filter on the function name. | |
| exclude_service | No | Service to exclude from results (use this when looking for sibling-repo implementations of work in your current service) | |
| intent_contains | No | Case-insensitive substring filter on the intent text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is met. The description adds real context beyond them: pagination behavior, that the index includes non-exported functions, and the reason for the limit cap ('the full org haystack is too large to return inline'). It does not mention auth or project-resolution failure modes, so it falls short of a 5.
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?
Dense but front-loaded: capability, then scope, then the file/compact recipe, then the sibling routing. Every sentence earns its place, though the file/compact clause is slightly packed and could be split for readability.
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?
With 11 optional params, no output schema, and 100% schema coverage, the description supplies the paging model, the filter surface, and the sibling alternative, which is most of what an agent needs. It leaves project/repo auto-resolution to the schema descriptions, which is 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?
Schema coverage is 100%, so the baseline is 3, but the description still adds value: the file+compact combination is explained as a way to read a file's surface, and it flags exclude_service as the sibling-repo lever. These are usage-level semantics the schema alone doesn't convey.
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 (list indexed functions) plus the scope of the index ('every function with an intent, not just exported ones'). It explicitly distinguishes itself from the sibling search_by_intent, so an agent can route without opening either schema.
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?
Gives concrete scenarios ('browse what a service contains or compare what sibling repos have built'), a file-scoped recipe, and an explicit exclusion routing concept queries to search_by_intent. When-to-use and when-not-to-use are both covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List this workspace's Carrick projects and their connected repos. Call it when unsure which project or repo value to pass. Metadata only, no scan data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely useful boundary: "Metadata only, no scan data," telling the agent this will not return heavy analysis output. It doesn't discuss return shape or ordering, keeping it out of 5 territory.
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 short sentences, each earning its place: what it lists, when to call it, and what it does not return. The purpose is front-loaded with no redundant restatement of the title.
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?
With no parameters, no output schema, and annotations carrying the safety profile, the description supplies everything needed: the resource, the trigger, and the metadata-only scope. Slightly more on the return shape (project/repo identifiers) would make it fully self-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 tool takes zero parameters, so there is nothing for the description to document and no schema gap to compensate for. Baseline for a no-parameter tool 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?
States a specific verb and resource — listing this workspace's Carrick projects and their connected repos — so the agent knows exactly what comes back. It does not explicitly differentiate itself from siblings like list_services or get_project_map, but the resource is distinct enough to be actionable.
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?
"Call it when unsure which project or repo value to pass" gives a concrete trigger condition for use, which is exactly the discovery aid an agent needs before other tools. It does not name competing alternatives or exclusions, so it falls 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.
List every service in the project with endpoint and call counts. Call it when unsure what exists or which repo owns a name. For the call graph, use get_service_graph.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds value beyond those annotations by disclosing what the result contains (endpoint and call counts) and that it enumerates the whole project. It stops short of mentioning pagination or result ordering, but that is a minor gap given the rich annotation coverage.
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 tight sentences: the resource scope and payload first, then the usage trigger, then the disambiguation pointer. Every sentence earns its place with no 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?
There is no output schema, so the description does carry return-value burden and it does so by naming the fields returned (services with endpoint and call counts). Combined with the annotated safety profile and full schema coverage, an agent has enough to call it correctly; only pagination/volume behavior is unstated.
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% and both parameters are fully documented there (repo resolution and project slug auto-resolution). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies. Note both parameters are optional, which the schema already conveys.
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 (list every service in the project) plus the returned fields (endpoint and call counts). It also explicitly differentiates from the sibling get_service_graph by naming it, so an agent can disambiguate without opening the schema.
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?
Gives an explicit trigger condition ('when unsure what exists or which repo owns a name') and routes the call-graph use case to a named alternative (get_service_graph). Both when-to-use and when-to-use-something-else are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the files that set up repos on Carrick (the GitHub Actions workflow, the Carrick skill, carrick.json and the Claude Code hooks) with instructions that seed carrick.json from the proposal that carrick init wrote and end in the first scan when a repo needs one from this machine. Pass every repo you are setting up in repos to get one answer for all of them. Create the files on a branch and open a PR per repo.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| repos | No | Every repo you are setting up, as owner/repo. One call answers for all of them; the project resolves from the first when `repo` is omitted. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly says it will 'Create the files on a branch and open a PR per repo,' a side-effecting write operation, while the annotations declare readOnlyHint=true. This is a direct contradiction of the structured safety profile, so per the rules it scores 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 core purpose is front-loaded, but the first sentence is overloaded with parenthetical file lists and an awkwardly claused workflow description, making it dense to parse. The batching and PR instructions are separate, which helps structure.
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 multi-file generation tool, the description covers what is created and the intended workflow, and no output schema means return values need not be explained. But it omits permissions/auth requirements and the reversibility of the branch/PR side effects, and the readOnly conflict undermines confidence in the stated behavior.
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 schema already documents `repo`, `repos`, and `project` including the batching behavior and fallback resolution. The description's note that passing `repos` yields 'one answer for all of them' merely restates the schema, so no meaningful value is added.
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 — generate the Carrick setup files — and enumerates exactly what gets produced (GitHub Actions workflow, Carrick skill, carrick.json, Claude Code hooks). This clearly separates it from the read/query siblings like get_project_map or list_services.
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 practical guidance to pass all repos in `repos` for a single answer, and describes the intended end-to-end flow (seed carrick.json from the `carrick init` proposal, end in first scan). However, it never states when NOT to use it or names any alternative among the siblings, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search every function in this project by what it does, including sibling repos you do not have checked out. Pass a plain-English concept ('verify a webhook signature'); matches need no keyword overlap. Use it before writing any helper, parser, validator or domain function, even when you are sure it is new — grep can prove a name is absent but never that the behaviour is. A row whose only tie to the query is a word most functions share is counted in the response rather than ranked. To browse instead, use list_function_intents. For a set of functions you are about to write or have just written, and for a whole-project reuse audit, use find_similar.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Your repo as owner/repo (git remote) or just the repo name. Resolves which Carrick project to query. | |
| query | Yes | Plain-English description of what the function should do (e.g. 'verify webhook HMAC signature', 'normalize email addresses') | |
| top_k | No | How many top matches to return (default 8). Keep tight — the agent should drill in on a few good matches rather than skim a long list. | |
| offset | No | Rank offset into the matches (default 0). Pass the `next_offset` from a previous call to page through. | |
| compact | No | Return locator-only rows (name, path, lines, similarity) instead of full detail. Use for wide enumeration. | |
| project | No | Carrick project slug to query. Omit to auto-resolve via `repo`, or omit both when the workspace has one project. | |
| also_phrased_as | No | Up to 2 further wordings of the same concept, such as the mechanism ('sha256 of a JSON body') beside the purpose ('hash a value to a cache key'). Purpose wording and mechanism wording reach different functions, so one call runs both and returns one deduped list, with matched_phrasings on each row naming the wordings that found it. For separate questions, call the tool once per question. | |
| similarity_threshold | No | Cosine-similarity floor for inclusion (default 0.3). Raise to filter weak matches; lower to surface more candidates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so credit goes to what the description adds: no keyword overlap is required, weakly-tied rows are counted rather than ranked, and multiple phrasings are deduped into one list with matched_phrasings. It stops short of describing return volume/ordering in detail, but the behavioral picture is notably richer than the annotations alone.
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?
Dense but front-loaded: purpose and usage come first, then alternatives. Every sentence carries information, though the 'word most functions share' nuance is slightly more detail than an agent needs at selection time.
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?
With 8 parameters, no output schema and existing annotations, the description covers the non-obvious behaviors an agent needs: no keyword-overlap matching, deduping across phrasings, and paging via next_offset (schema-documented). Return row shape is only partially described, but nothing critical to calling 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?
Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: query is a plain-English concept needing no keyword overlap, which shapes how an agent should phrase it. It also clarifies that repeated questions require separate calls, complementing the schema's also_phrased_as note.
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 precise verb and resource ('search every function ... by what it does') plus scope ('including sibling repos you do not have checked out'). It is immediately distinguishable from list_function_intents (browse) and find_similar (sets/audit), so an agent can route without opening schemas.
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?
Gives an explicit when-to-use trigger ('before writing any helper, parser, validator or domain function, even when you are sure it is new') and a memorable when-not rationale ('grep can prove a name is absent but never that the behaviour is'). It also names both alternatives and the conditions that select them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_findings1 field changedInput schema / properties / kindAdded value: +{
+ "description": "One kind of finding: \"type_mismatch\" or \"similar_functions\". Omit for every kind.",
+ "enum": [
+ "type_mismatch",
+ "similar_functions"
+ ],
+ "type": "string"
+}get_findingsCodebase intelligence for AI agents — dead code, blast radius, ownership.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Search indexed code, trace dependencies, assess change impact, and recall repository memory.
Add one secure layer between your agents and this server.
