Governed AI agents for the software your company already runs. 400+ connectors behind one org-wide endpoint, where every call resolves against the current role of the person the agent acts for, not against the connection. Works with Claude, ChatGPT, Cursor, any MCP client, and the Elaichi Agent.
Scored across 52 tools
Most tools are cleanly separated by resource and action, with detailed descriptions that clarify boundaries. A few overlapping families exist—tool execution (execute_tool, toolbox.execute, synthetic_tool.execute) and tool discovery (search_tools, connector.list_tools, connection.list_tools)—but the descriptions are thorough enough that a careful agent can reliably pick the right one.
The overwhelming majority follow a consistent elaichi__resource__action pattern with snake_case, which is predictable and readable. The two standalone tools, execute_tool and search_tools, break the prefix convention but are still clearly named and easily identifiable as general-purpose utilities.
52 tools is far above the 25+ threshold the calibration considers excessive. While the domain is broad, many operations are highly granular (e.g., separate get/list/create/update/set_entries/share for each resource), and the surface could be consolidated without losing functionality.
There are significant lifecycle gaps: descriptions repeatedly reference operations that are not exposed as tools, such as connection.unshare/delete/transfer, toolbox.unshare/delete, template.unshare/delete, member.delete, role.update/delete, and the entire restriction.* API. Agents cannot revoke, delete, or fully manage these resources through this surface, which will cause failures when users request those actions.
File a request asking an org admin to grant access to a tool that just refused you — the operation behind a "blocked" result’s can_request_access flag. Only ever call this right after a tool call came back refused for permission or restriction (never for scope — that refusal is between you and your own client and no admin can fix it, so it never carries can_request_access). Pass the exact tool name and reason the refusal named, and the exact permission string too when reason is "permission" — never invent or guess a permission, and never pass one at all when reason is "restriction" (the request record must not become a way to learn which rule blocked you, so a restriction-reason call that names a permission is rejected). Filing twice for the same thing while the first request is still open does not create a second one — it returns the existing request (its own status tells you whether that was a fresh file or a repeat), so it is safe to call again if you are unsure whether one already exists. This only creates a RECORD for a human to review; it does not itself grant anything, and nothing about a tool becomes usable because you filed a request. Returns the request with can_withdraw.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional short context for the admin reviewing this, in the requester’s own words. | |
| tool | Yes | The exact tool name the refused call used, taken verbatim from the refusal — or, when resource_type is "connector", the connector slug. Never a name you composed yourself. | |
| reason | Yes | The refusal’s own reason, verbatim — "permission" or "restriction". Never "scope"; a scope refusal has no admin-side fix, so it never offers this operation in the first place. | |
| permission | No | Required, and must be a real permission name, when reason is "permission" — the exact string the refusal named. Omit entirely when reason is "restriction"; sending one there is rejected. | |
| resource_type | No | What is being asked for. Omit (or "tool") for the ordinary case: a tool call came back refused. Pass "connector" ONLY when the person is asking for a whole connected app they cannot reach at all — then `tool` carries the connector slug instead of a tool name. Never guess between the two: use whichever the refusal itself was about. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations: it discloses the idempotent-like behavior when a request is already open, states that no access is actually granted, explains that passing a permission on a restriction-reason call is rejected, and names a field on the return (`can_withdraw`). This is rich behavioral context for a mutation-like operation.
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 long, but every sentence carries operational weight: triggering condition, exclusion of scope, parameter constraints, retry behavior, and result semantics. It is front-loaded with the core purpose and contains no filler or repetition beyond what is useful for safe invocation.
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 and the absence of an output schema, the description is remarkably complete. It covers when to call, when not to call, how to populate every parameter, edge cases around repeated requests, and what the response signifies. An agent has enough context to invoke it correctly without external knowledge.
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 already 100%, so the baseline is 3. The description adds value by emphasizing that tool/permission values must be taken verbatim from the refusal, that invented permissions are forbidden, that omitting permission on restriction calls is mandatory, and that resource_type='connector' has a special meaning. It mostly reinforces the schema's own wording, but the added rationale earns a 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 description opens with a specific verb and resource: 'File a request asking an org admin to grant access to a tool that just refused you.' It ties the operation to a concrete, recognizable condition (a refused result's can_request_access flag), which clearly distinguishes it from the access_request get/list/resolve/withdraw siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is explicitly gated: 'Only ever call this right after a tool call came back refused for permission or restriction (never for scope...).' It also explains when retrying is safe, when permission must be omitted, and that the operation only creates a review record rather than granting access. This removes almost all ambiguity about when the tool should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one access request by id. No permission gate here — like the REST route it mirrors, visibility is computed per-caller instead: an admin (member:manage) can read any request, and anyone else can read only their OWN, with resolved_by resolved to a name/email for an admin and left as a bare id otherwise (the same split GET /access-request/:id documents — resolving that id into a profile is a member-directory lookup this operation does not hand a plain member for free). Everyone else’s request is a 404, not a permission error — its existence is not something a bystander gets to learn. Returns the record with can_resolve for an admin or can_withdraw for the requester. Sensitive read: returns records an operator treats as confidential (audit history, credential metadata, offboarding detail). Read-only, but not harmless — do not echo the contents further than needed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Access request id (`areq_…`) from access_request.list, or from the id an access_request.create call just returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses far more than the readOnlyHint/idempotentHint annotations: per-caller visibility, 404 instead of permission error, resolved_by formatting differences between admins and non-admins, can_resolve/can_withdraw response fields, and a warning that this is a sensitive read whose contents should not be echoed. No contradiction with 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 long but dense: nearly every sentence earns its place by adding a behavioral constraint or clarifying a security-relevant detail. A few parentheticals repeat the same REST-route reference and could be tightened, which keeps it from a 5.
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-one-by-id tool with no output schema, the description covers all call-critical facts: access control, 404 hiding of existence, resolved_by behavior, returned capability flags, and sensitivity. Nothing material 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%, and the id parameter is already well documented with its areq_… format and provenance from list/create. The description does not add significant parameter-level meaning beyond saying the operation is keyed by id, 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?
Opens with a crisp verb+resource statement, 'Read one access request by id,' which clearly distinguishes it from access_request.list and the other access_request siblings. It further specifies per-caller visibility and return capabilities, eliminating ambiguity about what this tool does and what it returns.
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 concrete usage conditions: an admin with member:manage can read any request, a non-admin can only read their own, and anyone else gets a 404. It does not explicitly name the list/create siblings as alternatives or provide an explicit when-not-to-use statement, so it is not a perfect 5, but the context for when this tool applies is very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Access requests members have filed — the ADMIN QUEUE by default, or the CALLER’S OWN requests with mine: true. The default needs member:manage (the same permission that gates inviting people and changing roles, because acting on a request always ends in one of those) and is refused without it; mine: true needs nothing beyond org membership, the same nothing that filing a request needed, and is how the person who filed one finds it again. Use mine: true whenever the question is about the user’s own asks ("did my request go through", "what have I asked for") — the default answers a different question and will refuse most people. status defaults to "pending" (the open queue) when omitted; pass "all" to see the full history including withdrawn ones. q matches the requested TOOL name or the requester’s own note (not the requester’s name — resolve that from the requester field on each row instead, and not tool_label, which is resolved outside the searchable store). Admin-queue rows carry requester and, once resolved, resolved_by — both { id, name, email } — plus can_resolve, which is false on the caller’s OWN row: nobody decides their own request, so offer access_request.withdraw there instead of a decision — that row’s can_withdraw is true, because a queue row carries both capabilities. mine: true rows are the requester’s own narrower shape instead — can_withdraw, and a bare resolved_by_user_id rather than a resolved name, because resolving an id into a name and email is a member-directory lookup this view does not hand a plain member for free. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Page by sending nextCursor back as cursor until it is null. Sensitive read: returns records an operator treats as confidential (audit history, credential metadata, offboarding detail). Read-only, but not harmless — do not echo the contents further than needed.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Case-insensitive substring of the requested tool name or the requester’s note, matched before paging. | |
| mine | No | True to list only the requests THIS user filed, which needs no permission. Scoped to the signed-in user server-side — there is no field here that could name somebody else, and asking for another person’s requests is not something this operation can do. Omit (or false) for the org-wide admin queue, which needs member:manage. | |
| limit | No | Rows per page, 1–200 (default 50). Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. | |
| status | No | Defaults to "pending". Pass "all" for the full history. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations indicating readOnlyHint, idempotentHint, and non-destructive nature, the description goes far beyond these basics. It discloses the sensitive nature of the data, the security implications of the read, and the nuanced behavior of can_resolve and can_withdraw fields. It also explains the rationale behind 'nobody decides their own request' and the difference in data shapes between admin and mine views. This is exemplary behavioral transparency that significantly aids correct usage.
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 long and dense, packing a lot of information into a single paragraph. While every sentence adds value, the structure could be improved with headings or bullet points to improve scannability. The first sentence does front-load the core purpose, but the description is not concise in the sense of quick readability. It is information-dense but not easily digestible.
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 (two modes, permission requirements, pagination, field semantics, sensitivity), the description covers everything an agent needs to call it correctly: defaults, when to switch to mine:true, pagination handling, status filtering, and caveats like camelCase and field resolution. There is no output schema, so the description adequately explains the return format. The description is complete for even a complex 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?
The schema already has 100% coverage with detailed descriptions for each parameter. The description adds extra context on top, such as the semantics of q (matching tool name or note, but not requester name or tool_label) and the default behavior of status. However, the schema descriptions are already comprehensive, so the description is a complement rather than a necessity. Still, it provides additional nuance that improves the agent's understanding, so a 4 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 lists access requests, with a clear distinction between the admin queue (default) and the caller's own requests (mine: true). It also explicitly names the alternative tool for the user's own requests, differentiating it from other list tools. The verb 'list' and the resource 'access requests' are specific, and the description distinguishes it from sibling tools like access_request__get and access_request__resolve.
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 explicit guidance on when to use mine: true versus the default admin queue, including concrete examples of the questions each answers. It also mentions the permission requirements (member:manage vs. none), and what status values to use. This is excellent routing guidance that goes beyond generic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approve or deny a pending access request that SOMEONE ELSE filed. Needs member:manage, and refuses (403) a request the caller filed themselves however many permissions they hold — a decision is a record that a second person reviewed the ask, and one signed by its own requester reads downstream exactly like one that was not. An admin who no longer needs what they asked for uses access_request.withdraw on their own row instead. THIS RECORDS A DECISION — IT DOES NOT GRANT ANYTHING, with one exception that is the reason this is refused here: approving a reason:"restriction" request in the Elaichi web app now actually LIFTS the restriction it names, and restrictions are read-only on this surface (see restriction.list), so that must never happen by the back door. Approving a reason:"permission" request only sets this request’s own status and an optional note back to the requester; the requester’s role and restrictions are completely untouched, and nothing about what they can call changes because of this call. To actually widen what they can do, follow up with member.set_roles or the restriction APIs. Refuses (error) a request that has already left "pending" — a decision is recorded once. Returns the resolved request. NOT CALLABLE FROM ANY AI SURFACE, in-app agent or MCP: this needs step-up reauthentication (confirming it is really you), which neither surface can ask for, so every call from here is refused — denials included, since the gate is on the route and not on the decision. Say what needs doing and tell the user to do it in Governance → Access requests in the Elaichi app.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Access request id (`areq_…`) from access_request.list. Must be somebody else’s request — a row whose `can_resolve` is false is either already decided or your own, and both are refused. | |
| note | No | Optional note back to the requester explaining the decision. | |
| decision | Yes | The decision to record. Not "withdrawn" — only the requester can withdraw their own request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the sparse annotations (readOnlyHint false, destructiveHint false) to disclose that the call records a decision rather than granting access, that it refuses self-filed requests, that it errors on already-resolved requests, and that it is blocked at the route for AI callers due to reauthentication requirements. It even explains the one dangerous exception (approving a restriction request) and why it's refused. No contradiction with annotations; the description adds substantial behavioral context.
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 dense and long, covering many edge cases and security warnings. It front-loads the core purpose and then layers constraints. While every sentence earns its place given the complexity, the verbosity hurts scanability; a tighter structure with bullet points or a clearer separation of 'what it does' vs. 'what it doesn't' would improve it. It is appropriately sized for the context but not concise.
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 tool that is effectively uncallable from AI surfaces, the description fully prepares the agent: it states the return value (the resolved request), the exact failure modes, and the proper user-facing alternative. Given the lack of an output schema, the description supplies the necessary behavioral contract. Nothing an agent needs to handle this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description enriches parameters beyond the schema: it clarifies that 'id' must be somebody else's request and that a row with can_resolve=false will be refused, explains that 'note' is an optional reply to the requester, and clarifies that 'decision' cannot be 'withdrawn' because only the requester can withdraw. This adds actionable meaning to each field.
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 opens with a clear verb-resource pair ('Approve or deny a pending access request') and immediately scopes it to requests filed by someone else, which differentiates it from the sibling access_request.withdraw (own requests) and the read-only get/list tools. The statement 'THIS RECORDS A DECISION — IT DOES NOT GRANT ANYTHING' crisply disambiguates its effect from permission-granting tools like member.set_roles.
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 states when to use (deciding someone else's request) and when not (own request → withdraw), and names the exact alternative. It also flatly declares the tool is NOT CALLABLE FROM ANY AI SURFACE and instructs the agent to redirect the user to the app, so the agent knows it should never invoke it. This is definitive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel your own pending access request — e.g. because you no longer need the tool, or you got access another way. Only the request’s own requester may withdraw it, and only while it is still "pending"; anyone else’s id, or a request that was already approved/denied/withdrawn, is refused. Returns the withdrawn request.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Access request id (`areq_…`) — must be your own, from what access_request.create returned or your own row in access_request.get. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false (not read-only, not idempotent, not destructive), so the description carries the burden. It discloses who can act, the state precondition, refusal cases for invalid ids/statuses, and the return value. This goes well beyond the bare schema, though it doesn't detail the resulting state transition (e.g., status changes to 'withdrawn') or error response format.
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 earning its place: action plus rationale, constraints/refusals, and return value. The content is front-loaded with the core purpose and the examples are brief but helpful. No fluff or procedural repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema and all-false annotations, the description is complete: it states the action, who is allowed, the valid state, what gets refused, and what is returned. An agent has enough to decide when and how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a detailed description of 'id'. The tool description adds extra meaning by tying 'id' to the 'pending' status and clarifying that anyone else's id is refused. This reinforces and extends the schema, adding the state constraint that isn't present there.
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 opens with the specific verb 'Cancel your own pending access request', which precisely names the action and resource. It also distinguishes this tool from siblings like resolve or create by emphasizing 'own' and 'pending' – an agent can immediately tell what this tool is for.
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 clear when-to-use context with examples ('no longer need the tool, or you got access another way') and explicit when-not conditions: only the requester may withdraw and only while pending, with refusal for other states. It doesn't explicitly name an alternative tool like resolve for handling others' requests, but the exclusion constraints make the boundary unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start connecting a third-party account. Creates the connection with status "pending" and returns { connection, connect_url }. Elaichi cannot finish the provider’s login on the user’s behalf — connect_url is a one-time connect session a HUMAN opens in a browser, and the connection only becomes "active" once they have. Never ask for, accept, or repeat a credential in chat — no operation here takes one. When you already know which app the user means, resolve connector_slug with connector.list first; whether you may omit it otherwise depends on the surface, see below. shares defaults to empty, which makes the connection private to the caller (needing only connection:create); passing any entries shares it with a person, a team, or the whole organization in the same call and additionally requires the connection:share permission — refused, not silently dropped, without it. Prefer leaving shares empty unless the user actually asked for a shared account; access can always be granted afterwards from the “Manage access” action on the Connections page in the Elaichi web app, which this catalog does not expose as its own operation. There is no Connect button and no connector picker here, so connector_slug is required — resolve it with connector.list before calling. Handing the link over is your job. The result repeats connect_url on its own line in a second content block. Put that URL in your reply, as a clickable link if you can, and tell the user to open it. Do not wait for them in this turn: end your reply, and call connection.get later to see whether status became "active".
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Display name. Defaults to the connector’s label. | |
| shares | No | Optional grants to create the connection with, applied as part of the same create: if any entry names someone who cannot be granted access (a suspended member, a team from another organization, or yourself) the whole call is refused and NO connection is created. Defaults to empty (private to the caller). Each entry additionally requires the connection:share permission on the whole call. | |
| connector_slug | No | Provider slug from connector.list, e.g. "slack". Resolve it with connector.list rather than guessing. Whether it may be omitted depends on the surface, see this tool’s description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say the operation is not read-only, destructive, or idempotent, so the description carries the behavioral burden. It discloses the pending status, the one-time human-opened session, the inability of Elaichi to finish login, the permission requirement and failure mode for shares, and the fact that the connection only becomes active later.
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 information-dense and front-loaded with the core result, but it is lengthy and repeats the 'connector_slug is required / resolve with connector.list' instruction twice, and the 'depends on the surface, see below' clause is never fully resolved. Most sentences earn their place, but the redundancy and one dangling reference make it more verbose than necessary.
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 high-stakes connection-creation flow with no output schema and minimal annotations, the description covers prerequisites, side effects, permissions, output shape, required follow-up (handoff, later polling), and common failure conditions. Nothing an agent needs to execute the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already defines each parameter. The description adds real meaning beyond it: connector_slug must be resolved from connector.list, shares defaults to private and requires connection:share when present, and name defaults to the connector label. The prose is slightly ambiguous about when connector_slug may be omitted, preventing a 5.
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 begins with a specific action ('Start connecting a third-party account') and states the exact result: a pending connection plus { connection, connect_url }. It also clarifies the browser handoff, distinguishing this tool from any provider-login or listing 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?
It gives explicit preconditions and sequencing: resolve connector_slug with connector.list first, hand the connect_url to the user, do not wait, and poll with connection.get afterwards to detect 'active'. The security guidance (never ask for credentials) and the advice to prefer empty shares over sharing in this call are also actionable when-to/how-to instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one connection by id: id, name, display_label, account_label, connector_slug, status, and its owner — owner_user_id plus owner: { id, name, email } — never the credential. It carries NO grant information: there is no shares key and no access_summary on this response at all, so when the question is who else can reach the connection, use connection.list, whose every row carries access_summary. The standard use is confirming that status became "active" after a user opened a connect_url from connection.create or connection.reconnect — this is the ONLY operation that answers that, because connection.list_tools ignores status entirely. Returns the object directly and errors when the id is unknown or not visible to the caller — visible meaning owned or shared with them, and ONLY that: a connection:view/:manage permission does not widen this, so an admin auditing the org cannot read a connection nobody gave them access to.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Connection id (`conn_…`) from connection.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond those: the response never contains credentials, never contains grant info, errors on unknown or non-visible ids, and a connection:view/:manage permission does not broaden visibility. This is exactly the kind of behavioral disclosure an agent needs.
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 long but front-loaded and information-dense. Each sentence adds a distinct and valuable fact: returned fields, credential exclusion, grant exclusion, standard use, and visibility semantics. It is structured well, though slightly verbose for a simple get-by-id operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description covers everything an agent needs: return shape, exclusions, typical use case, error conditions, and auth/visibility edge cases. There is no meaningful gap that would cause an agent to misuse or misselect this 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 coverage is 100% for the single required parameter, and the schema already documents that id is a `conn_…` string from connection.list. The main description doesn't add new parameter semantics beyond what the schema provides, so the 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 opens with a specific verb and resource: "Read one connection by id" and enumerates the exact fields returned. It also differentiates this tool from siblings by explicitly stating what it is not (no credential, no grant information), making it unambiguous alongside connection.list and connection.list_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?
Gives explicit when-to-use guidance: confirming status became "active" after a connect_url from create/reconnect, and states this is the ONLY operation to answer that. It also directs the user to connection.list when the question is about who else can access the connection, naming the alternative and the condition clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated third-party accounts the caller can use — their own, plus anything explicitly shared with them or their teams. A connection with NO shares is private to its owner and is never listed for anyone else, whatever permission they hold — this cannot answer "what has Priya connected" and must not be reported as if it could; only its owner can. There is no org-wide listing: an org owner or admin sees exactly this same set, never every connection in the organization, whatever permission they hold. A connection is one account of one connector with a credential held in the vault; this is what "are we connected to Slack" means. Each row carries a conn_… id, name, connector_slug, owner_user_id with an owner: { id, name, email } beside it — say who owns a shared connection by name, never by id — and status: "active" is usable, "pending" means nobody ever finished the provider login, "needs_reauth" means it broke and connection.reconnect is the repair. Every row also carries access_summary, a BOUNDED who-else-can-reach-it rollup — { org_level, team_count, user_count, total, preview } — never a full grant list however many grants exist, so answer from its counts ("shared with 3 people and 1 team") and send the user to the connection’s Manage access tab when they need every name. There is no shares key on a row. Every row also carries access_via — how the CALLER reaches that connection: "owner", "direct" (shared with them by name), "team" (with access_via_team: { id, name } naming the team) or "org" (shared organization-wide). It is about the caller alone, never about anyone else, so it is present on every row including ones where access_summary is withheld — and it answers "why can I see this" without disclosing who else can. Credentials are never included. Narrow before paging rather than walking every page: connector_slug answers "do we have Slack" exactly (one slug, or several) and is the right choice when the caller names a provider, owner_user_id narrows to one owner within what the caller can already see (it never reaches a private connection, so it still cannot answer "what has Priya connected"), status takes one lifecycle value, and q is a case-insensitive substring match against the connection’s name, its account label, its connector slug, and the connector’s catalog label — so q: "slack" finds a Slack connection even if a person renamed it to something else, and q: "sheets" finds one on google-sheets even though the slug does not spell it that way. Unrelated to sso_connection.*, which is how people log IN to Elaichi. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Page by sending nextCursor back as cursor until it is null.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Case-insensitive substring match on the connection’s name, its account label, its connector slug, and the connector’s catalog label, applied before paging. `connector_slug` below is still the right choice for an exact "only these connectors" filter. | |
| limit | No | Rows per page, 1–200 (default 50). Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. | |
| status | No | Narrow to one lifecycle status, applied before paging. | |
| owner_user_id | No | Narrow to connections owned by one user, within what the caller can already see. It is a filter, not a way in: another member’s private connections stay invisible, so this cannot enumerate what someone has connected. An id nobody owns returns an empty page. | |
| connector_slug | No | One or more connector slugs (e.g. ["slack"]) — take a slug from a row you have already seen or from connector.list, and do not invent one. This is the right way to ask "are we connected to X"; it matches exactly, applied before paging. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: private connections are never surfaced, access_summary is bounded, there is no shares key, credentials are never included, and pagination returns camelCase cursors. Nothing in the description contradicts 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 long and occasionally repetitive ('whatever permission they hold' and 'never' are used multiple times), but it is front-loaded with the core scope and each paragraph covers a distinct concern: row shape, access semantics, filters, and pagination. For a tool with tricky access-control semantics, the density is justified, though it could be tightened without losing meaning.
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?
Even without an output schema, the description fully explains return shape, row fields, status semantics, access_summary, access_via, credentials exclusion, and pagination behavior. The only minor omission is that the disconnected status value is not explained, but active/pending/needs_reauth are among the meaningful states and the overall coverage is enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all six parameters in detail, so the baseline is 3; the description earns extra credit by adding operational examples such as q: 'slack' finding renamed connections and q: 'sheets' matching google-sheets, plus lifecycle meanings for status. It clearly differentiates connector_slug from q and explains cursor round-tripping, though it largely restates what the schema descriptions already say.
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 first sentence states a specific verb and resource: 'List the authenticated third-party accounts the caller can use' and immediately scopes it to the caller's own plus explicitly shared accounts. Later paragraphs clarify it is about connections, not org-wide inventory, and explicitly separate it from sso_connection.*, so an agent can distinguish it from sibling 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 gives explicit when-to-use guidance per filter: connector_slug for exact provider checks, q for substring search, owner_user_id only within the caller's visible scope, and status for one lifecycle value. It also states when not to use the tool ('this cannot answer what has Priya connected', 'there is no org-wide listing') and names related tools like connection.reconnect and sso_connection.*.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the tools one authenticated account is ALLOWED to run: the connector’s catalog filtered by the restrictions in force for this caller. It does not look at the connection’s status — a "pending", "needs_reauth" or "disconnected" connection returns exactly the same list as a working one while actually running none of them — so this can never confirm that a connection authenticated, and a non-empty list here is not evidence that it did. Use connection.get and read status for that. Use this whenever you hold a conn_… id, and always when assembling toolbox entries, because an entry naming a restricted tool is rejected. It is no longer the only restriction-filtered view: connector.list_tools applies the same per-caller clamp, so for the same connector the two return the same set — what this one adds is that you name the ACCOUNT rather than the slug. If governance has blocked the whole connector for you, this REFUSES with a permission error rather than answering an empty list — the same as connector.list_tools, and the same as the REST route behind it. So an empty tools here means the provider genuinely has nothing to list, never "blocked for you"; read connector.get’s restricted to state the block without provoking the refusal. The connection itself stays describable either way — connection.get is not gated — so you can always explain WHY the listing refused. Returns { connection_id, connector_slug, tools: [...], nextCursor, prevCursor } — the rows are under tools, NOT under result, so this is not the standard list envelope. The restriction filter is applied BEFORE paging, so every row on every page is one this caller may actually run and the cursor never counts rows it would have hidden. limit defaults to 200, which is the whole allowed set for almost every provider; a non-null nextCursor means there are more, and you page by sending it back as cursor until it is null.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Connection id (`conn_…`) from connection.list — not a connector slug. | |
| limit | No | Rows per page, 1–200. Defaults to 200 — the whole set in one call for almost every organization — rather than the 50 the other lists here default to. Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavioral context beyond the readOnly/idempotent annotations: connection status is irrelevant, a blocked connector causes a refusal rather than an empty list, the response uses a non-standard envelope, and paging filters before pagination. No contradiction with 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 long but front-loaded with purpose and usage, followed by edge-case and paging details. Every major claim earns its place for a tool with subtle failure modes, though there is minor redundancy around connector.list_tools equivalence and authentication caveats.
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?
Despite having no output schema, the description fully documents the return envelope, the location of rows under `tools`, paging behavior, default limit, refusal semantics, and how to disambiguate an empty list from a blocked connector. 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?
The schema already covers 100% of parameters, so the baseline is 3. The description adds meaningful semantics: limit defaults to 200 rather than 50, larger values are clamped, cursor is opaque and sent back verbatim, and id must come from connection.list. This exceeds the 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?
States a specific verb ('List'), resource (tools an authenticated account is ALLOWED to run), and the key filtering behavior (catalog filtered by per-caller restrictions). It explicitly distinguishes itself from the sibling connector.list_tools by noting the difference is naming the ACCOUNT rather than the slug.
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 when-to-use guidance: 'Use this whenever you hold a conn_… id, and always when assembling toolbox entries.' It also names alternative tools for related needs, such as connection.get for checking authentication status, and explains when connector.list_tools is equivalent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint a fresh connect_url for an existing connection whose status is "needs_reauth" (or still "pending"), and return it — the connection repairs itself once a HUMAN opens that one-time connect session and finishes the provider’s login, which Elaichi cannot do for them. Touches no credential and changes nothing else about the connection, so toolbox entries pinned to it keep working afterwards. Needs "edit" access to the connection, its ownership, or connection:manage over a SHARED one — connection:manage never reaches another member’s private connection (one with no shares). Returns { connection, connect_url }, the same shape connection.create returns. There is no Connect button here, so handing the repair link over is your job. The result repeats connect_url on its own line in a second content block. Put that URL in your reply, as a clickable link if you can, and tell the user to open it. Do not wait for them in this turn: end your reply, and call connection.get later to see whether status became "active".
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Connection id (`conn_…`) from connection.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
All annotations are false, so the description carries full behavioral disclosure. It thoroughly covers that the tool touches no credentials, changes nothing else, requires a human to complete the connection, has specific permission nuances, returns a specific shape, and repeats connect_url in a second content block. It also explains the post-call workflow. No contradiction with annotations exists.
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 one long paragraph but front-loads the core action and condition in the first sentence. It contains many necessary details (permissions, human step, output shape, follow-up). While somewhat verbose and could benefit from structure, every sentence contributes useful context, 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?
Given the tool's complexity, all-false annotations, and lack of an output schema, the description is remarkably complete. It covers when to use, prerequisites, side effects (none on credentials), return shape, and the required agent follow-up. An agent has everything needed to invoke the tool correctly and handle the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the only parameter `id` with 100% coverage, including its format (`conn_…`) and source (connection.list). The description adds no additional semantic meaning for the parameter beyond confirming it refers to an existing connection, so it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Mint a fresh connect_url') on a specific resource ('existing connection') under a specific status condition ('needs_reauth' or 'pending'). It clearly differentiates from sibling tools like connection create by focusing on reconnecting an existing connection, and even references connection.create's return shape to further define its role.
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 states when to use the tool (status 'needs_reauth' or 'pending') and gives detailed follow-up instructions (end reply, call connection.get later). It also clarifies permission requirements. However, it does not explicitly name alternative tools for conditions outside those statuses, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a connection’s display name. Nothing else moves: the credential, its shares, status and every toolbox entry pinned to it are untouched. Returns the updated connection.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Connection id (`conn_…`) from connection.list. | |
| name | Yes | New display name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the exact side-effect boundary: 'Nothing else moves: the credential, its shares, status and every toolbox entry pinned to it are untouched.' It also states the return value ('Returns the updated connection'), which is especially useful given there is no output schema. This is valuable behavioral context beyond the structured 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 focused sentences deliver the purpose, the side-effect guarantee, and the return value with no filler. The core action is front-loaded, and every clause adds necessary 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?
For a simple two-parameter rename tool with no output schema, the description covers purpose, scope of effects, and return value while the schema covers both parameters. There are no significant gaps that would prevent an agent from selecting and invoking the tool 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 the parameters are already well documented: id is a connection id from connection.list and name is the new display name. The description does not add further parameter-level detail, so the baseline score 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?
The description opens with a specific verb and resource: 'Change a connection’s display name.' It then distinguishes itself from sibling connection tools by clarifying that the credential, shares, status, and toolbox entries are untouched, so an agent immediately knows this is a narrow rename operation rather than a broader update, share, or reconnect.
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 clearly implies when to use this tool: when the only desired change is a connection's display name. The explicit statement that nothing else moves also sets an implicit boundary that this is not for altering credentials, shares, status, or toolbox entries. It does not name alternatives, but no sibling tool fills the same rename-only role, so the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one connector definition by slug: label, category, description, supported auth formats, tool_count and whether it needs a customer-supplied OAuth app. No credentials and no tool schemas — for the tools themselves use connector.list_tools. It also returns restricted: true when governance has blocked this whole connector for YOU. Read it before anything else, because connector.list_tools refuses a blocked connector outright and this is how you learn it without provoking the refusal. restricted: false does NOT mean "nothing is restricted for me" — it is the connector-level signal only, and a caller with individual tools blocked still sees false. tool_count is the PROVIDER’S total and is never filtered: it counts what the connector offers, not what you may run. The two differ whenever a restriction applies, and that difference is not yours to compute or report — do not subtract the rows connector.list_tools returned from tool_count and describe the remainder, because the size of what governance hid from you is an inference this API never states. Returns the object directly, and errors when the slug is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Connector slug from connector.list, e.g. "slack". Connectors are keyed by slug, never by a prefixed id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already marking it read-only and idempotent, the description adds deep behavioral context: the meaning of 'restricted', the unfiltered nature of tool_count, how restricted:false is not a global all-clear, and the explicit warning not to compute or report differences with list_tools. It also discloses error behavior for unknown slugs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place by presenting a distinct fact or warning. It front-loads the core purpose, then builds context for restrictions, tool_count semantics, and error behavior without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully compensates by explaining what the object contains, how the restricted flag behaves, what tool_count means, and what happens on an unknown slug. The tool is simple enough that nothing needed for correct invocation or interpretation is omitted.
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 single parameter slug is already fully documented in the schema with an example and a note about never using a prefixed id. The description does not add meaning beyond referring to lookup 'by slug', so the schema carries the parameter burden and 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?
The description opens with a specific verb and resource: 'Read one connector definition by slug' and enumerates the returned fields. It explicitly distinguishes itself from connector.list_tools by stating this tool returns no tool 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?
The description states when to use it ('Read it before anything else') and names the alternative for tool schemas ('use connector.list_tools'). It also explains the safety reason: connector.list_tools refuses blocked connectors outright, so this tool is the way to learn about that without provoking the refusal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse the catalog of third-party providers this organization can connect to (Slack, HubSpot, Google Calendar, …). A connector is a provider DEFINITION, not an account: nothing here is authenticated and nothing here is usable until someone creates a connection from it, so this cannot answer "what is our org connected to" — that is connection.list. Each row carries slug (the connector’s key everywhere else in this catalog — connectors have no id), label, category, description and byoa (true when the org must supply its own OAuth app first). No row carries a tool count: that lives on connector.get, one connector at a time, so "which connector has the most tools" cannot be answered from this list and must not be guessed from it. Every row carries restricted and, when it is true, restricted_by ("role" or "user") — governance has blocked that connector FOR YOU. A blocked connector is still listed, deliberately: presence here is not permission to use it, and absence means the provider genuinely is not in this catalog. Say the true one. When restricted is true, tell the person the connector exists and that they are blocked, and offer access_request.create with resource_type "connector" and the slug as tool — never claim no such connector exists, and never attempt connection.create or connector.list_tools on it, both of which refuse. restricted_by says only WHOSE rule layer blocked it, their role or their account; it never names the rule, who wrote it, or what else it covers, and neither may you. search and category are applied by the catalog before paging, so "is there a Slack connector" is one call rather than a walk through every page; category matches exactly, so take its value from the category of a row you have already seen rather than inventing one. Returns { result: [...], nextCursor } — no prevCursor on this one, so you can page forward but never back. limit defaults to 50 here, NOT to the whole catalog, and the catalog is far larger than one page: send nextCursor back as cursor until it comes back null, and never answer "which connectors are there" from the first page alone.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page, 1–200 (default 50). Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. | |
| search | No | Case-insensitive substring of the connector’s slug or label (e.g. "slack"), applied across the whole catalog before paging. | |
| category | No | Exact category string as it appears in these rows (e.g. "crm"). Not a substring and not a guess — an unknown category matches nothing rather than erroring. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavior beyond that: blocked connectors are deliberately still listed, `restricted_by` names only the rule layer and must never be elaborated, and the absence of a provider means it is genuinely missing from the catalog. It also discloses the pagination asymmetry ("no prevCursor on this one") and the trap that `limit` defaults to 50 rather than the whole catalog. No statement contradicts 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 strongly front-loaded and nearly every sentence carries a distinct constraint, but it is unusually long — over a thousand words for a 4-parameter list endpoint. Some admonitions repeat the same idea ("Say the true one" / "never claim no such connector exists", and the "neither may you" restatement in the restricted_by paragraph) and could be tightened without losing information. It is dense with value, yet overweight.
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 correctly supplies the return shape ({ result: [...], nextCursor }), the row's field set (slug, label, category, description, byoa, restricted, restricted_by), and complete paging rules. Combined with 100% schema coverage on inputs, an agent has everything required to invoke the tool correctly and to consume its results accurately — including the traps around blocked rows and first-page-only answers.
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 — every parameter already has schema-level documentation. The description adds operational value beyond that: search and category are applied before paging (making a one-call existence check possible), category values "must" come from an observed row rather than invention, and cursor paging must be followed "until it comes back null." This is more than the baseline but not exhaustive per-parameter enrichment.
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 first sentence names a specific verb and resource — "Browse the catalog of third-party providers this organization can connect to" — and immediately disambiguates the core concept: "A connector is a provider DEFINITION, not an account." It explicitly differentiates from siblings by naming what this tool cannot answer (org connectivity belongs to connection.list, tool counts belong to connector.get), so an agent can distinguish it 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?
The description gives explicit when-to-use and when-not-to-use guidance: "this cannot answer 'what is our org connected to' — that is connection.list" and "'which connector has the most tools' cannot be answered from this list." It also prescribes the exact fallback for blocked connectors — access_request.create with resource_type "connector" and the slug as `tool` — and explicitly forbids connection.create or connector.list_tools on those rows. This is textbook alternative-routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the tools a provider exposes that YOU are allowed to run, with each tool’s full JSON Schema. It is the connector’s own catalogue — no account and no credential is involved, so it answers "what could Elaichi do with X" before anything is connected — but it is NOT account-independent and NOT unfiltered: the organization’s restrictions for the CALLER are applied first, so two members can get different answers for the same slug, and neither is the provider’s full catalogue. If governance has blocked the whole connector for you this REFUSES with a permission error rather than answering an empty list — an empty list would be a false statement about the connector, where a refusal is a true one about you; call connector.get and read restricted to find that out without provoking it. Restrictions are per-caller, not per-connection, so for the same slug this returns the SAME set connection.list_tools does — reach for that one when you hold a conn_… id or the question is about a real account, and this one when all you have is a slug. They refuse identically too — neither answers an empty list for a blocked connector — so an empty tools from either one means the provider genuinely has nothing to list. Returns { slug, tools: [...], nextCursor, prevCursor } — the rows are under tools, NOT under result, so this is not the standard list envelope. limit defaults to 200, which is every tool of almost every connector in one call; a non-null nextCursor means this connector has more, and you reach them by sending it back as cursor until it comes back null. Never report a page whose nextCursor is not null as the connector’s complete tool list — connector.get’s tool_count is the count. Every row carries a full JSON Schema, so prefer a narrow question to paging the lot.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Connector slug from connector.list, e.g. "slack". | |
| limit | No | Rows per page, 1–200. Defaults to 200 — the whole set in one call for almost every organization — rather than the 50 the other lists here default to. Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, idempotentHint=true, openWorldHint=false) are consistent with the description, which then adds rich behavior beyond them: it REFUSES with a permission error when the whole connector is blocked rather than returning an empty list, restrictions are per-caller not per-connection, and it uses a non-standard envelope (rows under `tools`, not `result`). The warning never to report a page with a non-null nextCursor as complete is genuinely useful disclosure.
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?
Purpose is front-loaded in the first sentence, and the rest is a logical progression: caveats, sibling differentiation, envelope, pagination. However, the description is very long and contains somewhat philosophical phrasing ('an empty list would be a false statement about the connector, where a refusal is a true one about you') that could be trimmed without losing meaning. Most sentences earn their place, but a tighter rewrite would improve it.
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 carries the full burden of explaining the return value: { slug, tools: [...], nextCursor, prevCursor }, including the envelope gotcha. It covers the refusal-vs-empty distinction, the per-caller filter semantics, the default limit, clamping, and the complete pagination protocol. 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 coverage is 100% and the schema already documents slug, limit (1–200, default 200), and cursor. The description adds value beyond that: it explains that the 200 default differs from the 50 that other lists default to, that larger values are clamped rather than rejected, that cursor is opaque and must be taken verbatim from a previous nextCursor, and how pagination terminates. This goes beyond the schema's plain text.
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?
Opens with a specific verb+resource: 'List the tools a provider exposes that YOU are allowed to run, with each tool's full JSON Schema.' It immediately distinguishes itself from siblings — it is the connector's catalogue, filtered by the caller's restrictions, and explicitly contrasts with connection.list_tools and connector.get. The scope is unambiguous.
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 explicit when-to-use guidance: 'reach for that one when you hold a conn_… id or the question is about a real account, and this one when all you have is a slug.' It also instructs the agent to call connector.get and read `restricted` to check a block without provoking a refusal, and explains that connection.list_tools returns the identical set for the same slug. No inference is left to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a BUG to Elaichi — a connected app that behaved wrongly, or something broken in Elaichi itself. This is for defects, not for access: a tool that REFUSED you for permission or restriction is access_request.create, and a tool that is merely missing from your surface is usually search_tools, not a bug. Call it when the person says something is broken, wrong, or not doing what it should, and when a call failed for a reason that is nobody’s fault at this end — a vendor error, an empty result that should have had rows, a field that came back wrong. PASS WHAT YOU ALREADY HAVE, and do not interrogate the person for it: connector_slug and tool_name from the call that misbehaved, and error_text as the tool returned it, VERBATIM — a report carrying those three is actionable on sight, and one that says only "Notion is broken" is not and will be closed unanswered. Never paste the arguments you sent: they are the user’s own data, and the tool name plus the error is what identifies the bug. summary is what the PERSON was trying to do, in their words, one sentence. Filing twice for the same tool while your first report is open does not create a second one — it returns the existing report and created comes back false, so say "you already reported this" rather than implying a fresh one went in. This creates a RECORD for Elaichi to read; it does not fix anything, it cannot make the tool work, and you must not promise a timeline for it.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | "integration" when a connected third-party app misbehaved — the common case. "feature" when Elaichi itself did. | |
| detail | No | Anything else the person said that a reader would need. Optional; leave it out rather than padding it. | |
| summary | Yes | What the person was trying to do and what went wrong instead, one sentence, in their words rather than yours. | |
| tool_name | No | The exact tool name that misbehaved, as you called it (e.g. "Acme_HubSpot__create_deal"). | |
| error_text | No | The error or refusal the tool returned, verbatim and untrimmed. The single most useful field here. | |
| connector_slug | No | The connector’s slug, e.g. "notion" — REQUIRED when kind is "integration", because a report that does not name the app cannot be grouped with the others about it. Take it from the tool you called, never from the app’s display name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say the tool is not read-only, not idempotent, not open-world, not destructive. The description adds substantial behavior: it creates a record but does not fix anything, cannot make the tool work, must not promise a timeline, and duplicate filings return the existing report with created=false. No contradiction with 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 long but every sentence carries essential operational guidance. It is front-loaded with purpose and uses the rest to explain edge cases and anti-patterns. A slightly tighter phrasing could earn 5, but the length is justified given the tool's nuance.
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?
Despite no output schema, the description covers return behavior (duplicate returns existing report, created false), what makes a report actionable, what to include, what to avoid, and what the tool cannot do. It leaves no gap an agent needs 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 coverage is 100%, but the description goes far beyond the schema: it explains why connector_slug is required for integration, that error_text must be verbatim and untrimmed, that summary should be the person's words, and that tool_name must be the exact name as called. It also tells the agent never to paste arguments because they are user data. This adds meaning the schema alone lacks.
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 opens with a specific verb+resource: 'Report a BUG to Elaichi', and immediately disambiguates from access_request.create (permission refusals) and search_tools (missing tools). An agent can instantly tell what this tool is for and what it is not for.
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 explicit when-to-use conditions (person says something is broken, call failed for a vendor/empty-result/field-wrong reason) and explicit when-not-to-use (permission refusals → access_request.create, missing tool → search_tools). It even tells the agent to pass existing data rather than interrogate, which is critical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invite somebody who is not yet a member into this organization by email: mints a fresh accept link and emails it to them, the same as the Invite button in Settings → People. A member holds exactly ONE role, so role_ids must carry exactly one id (role.list) — the role they land with the moment they accept, the same cardinality member.set_roles enforces; team_ids is optional and puts them straight into those teams on acceptance. You cannot invite someone at a role that carries a permission you do not hold yourself — the same ceiling member.set_roles enforces. Refuses with a conflict when the address already belongs to a member of this organization; check member.list first if you are not sure. Some addresses are refused for reasons this operation will not disclose — treat that refusal as final rather than retrying the same address a different way. Returns the created invite record — id (inv_…), email, role_ids, team_ids, status, expires_at — plus email_sent; the raw accept link itself is never returned here, unlike the console’s copy-link view, because the email IS the delivery channel on this surface — if email_sent is false, tell the user delivery failed and that resending the SAME invitation is a human action in Settings → People, but inviting the address again from here is not blocked. To revoke a pending invitation, use invite.delete; to see who is still waiting, invite.list. NOT CALLABLE FROM ANY AI SURFACE, in-app agent or MCP: an invitation is a redeemable credential for an address the caller names, so it needs step-up reauthentication (confirming it is really you), which neither surface can ask for — every call from here is refused before anything is written or emailed. Say what needs doing and tell the user to do it in Settings → People in the Elaichi app.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Address to invite. Case-insensitive; stored lowercased. | ||
| role_ids | Yes | Exactly one role id (`role_…`, from role.list) — an invite carries exactly one role, the role the invitee holds the moment they accept. | |
| team_ids | No | Team ids (`team_…`, from team.list) the invitee joins immediately on acceptance. Optional; omit or send an empty array for none. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false and provide no safety signals, so the description carries the full burden. It discloses side effects, refusal behavior, non-disclosable address refusals, the non-return of the accept link, email_sent semantics, resend restrictions, and hard refusal from AI surfaces with the reason (step-up reauthentication).
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 long and dense, but every sentence carries operational information and the main purpose is front-loaded. Minor redundancy exists around role cardinality, which is stated in both schema and prose, preventing a perfect conciseness score.
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?
Despite having no output schema or meaningful annotations, the description fully covers what the return contains, delivery status handling, failure semantics, exclusions, and follow-up actions. An agent has everything needed to decide whether and how to invoke this tool, including the crucial instruction that AI surfaces should not call it at all.
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 substantial meaning: role_ids must be exactly one and the role is held upon acceptance, the permission ceiling parallels member.set_roles, team_ids places invitees into teams immediately, and email is case-insensitive and lowercased. This goes well 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 states a specific verb, resource, and mechanism: inviting a non-member by email, minting and emailing an accept link, and equates it to the Invite button in Settings → People. It also distinguishes itself from the console's copy-link view and from related invite operations.
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 explicit when-to-use context and names alternatives with conditions: check member.list for conflicts, use invite.list to see pending invites, and use invite.delete to revoke. It also explicitly states when the tool must NOT be called — from any AI surface — and instructs the agent to redirect the user to Settings → People.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List organization invitations nobody has redeemed or withdrawn — hardcoded, so accepted and revoked invites are never returned and their absence means nothing. Each row carries a server-computed status: pending while its link still works, expired once it ran out of time. An expired one is listed on purpose — it is the invitation a person is still waiting on, and it can be revoked (invite.delete) or replaced with a fresh one (invite.create); only RESENDING the exact same invitation (same link, new expiry) is a human action in the Elaichi web app, with no AI-surface equivalent. Ids are inv_…, and they are what invite.delete takes. For people who already joined, use member.list. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Page by sending nextCursor back as cursor until it is null. Sensitive read: returns records an operator treats as confidential (audit history, credential metadata, offboarding detail). Read-only, but not harmless — do not echo the contents further than needed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page, 1–200 (default 50). Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it warns that this is a sensitive read returning confidential data, that it is read-only but not harmless, and that expired invites are deliberately included. It also explains the server-computed status semantics, which annotations do not cover. No contradictions with annotations found.
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 dense but every sentence earns its place—it covers core behavior, exceptions, sensitivity, pagination, and related actions without redundancy. The most important scoping constraint is front-loaded, and the structure flows logically from function to usage to warnings.
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 list tool with no output schema, the description provides the return structure ({ result, nextCursor, prevCursor }), the id format, pagination mechanics, and sensitivity warnings. It also explains the meaning of expired status and the relationship to delete/create. 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?
Although the schema already documents both parameters (limit and cursor) at 100% coverage, the description adds crucial meaning: it explains the camelCase vs REST naming, how to page by sending nextCursor back as cursor, and that larger limit values are clamped. This goes beyond the schema's basic descriptions and enriches the semantics.
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 organization invitations that have not been redeemed or withdrawn, and explicitly distinguishes itself from siblings like member.list and invite.delete/create. It gives a precise verb, resource, and scope, leaving no ambiguity about what the tool returns.
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 this tool (for pending/expired invites) and when not to (for people who already joined, use member.list). It also clarifies that resending the same invitation is a human action with no AI equivalent, and explains pagination usage with nextCursor. This provides comprehensive routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one membership by USER id. Returns the record directly — user_id, status, via, joined_at, roles[], teams[], plus user: { id, name, email } — and errors when that user is not a member of this organization. To find someone by name in the first place, use member.list with q. Read this before member.set_roles, which replaces the role list wholesale.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The person’s USER id (`usr_…`). There is no separate membership id — every member.* operation is keyed by user id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful behavioral context beyond annotations by enumerating the exact return shape (user_id, status, via, joined_at, roles[], teams[], user object) and the error condition for non-members. This is strong but not exhaustive; it doesn't mention pagination, but that is not relevant for a single-record read.
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 composed of three sentences, all carrying substantive information: what the tool does, what it returns/errors, and how it relates to sibling tools. It is front-loaded with the core purpose and contains 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?
For a single-parameter read operation with strong annotations, the description is complete. It specifies the input key, the output fields, the error condition, and the relationship to sibling tools. No output schema is present, but the description supplies the necessary return information.
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 schema already explains that `id` is the user ID (`usr_…`) and that there is no separate membership ID. The description reinforces 'USER id' but adds no new parameter meaning beyond what the schema provides, so the 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 opens with a specific verb and resource ('Read one membership by USER id'), which clearly identifies what the tool does. It also differentiates itself from sibling tools by emphasizing that it returns a single membership record and by referencing member.list and member.set_roles explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides direct usage guidance: use member.list with `q` to find someone by name first, and read this before member.set_roles. It also clarifies the error condition (user not a member of this organization), giving the agent clear context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the people in this organization. Each row carries user_id (a usr_… id), status, join date, the roles and teams that person holds, and user: { id, name, email } — the name and email live outside the membership record and are attached here, so call people by name rather than reading a usr_… id back to the user. Going the other way, q matches name and email case-insensitively across the whole organization and filters before paging, so "find Bob" is one call, not a walk through every page. Every member.* operation, plus team.add_member and team.remove_member, takes the user_id you read here. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Page by sending nextCursor back as cursor until it is null.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Case-insensitive substring of a member’s name or email address, matched across the whole organization before paging. The only name-or-email → user_id lookup in this catalog. | |
| limit | No | Rows per page, 1–200 (default 50). Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and idempotent behavior. The description adds valuable behavior beyond that: q filters before paging, return fields are camelCase unlike the REST API, and pagination is done by sending nextCursor back as cursor. It does not mention auth or rate limits, but given the annotations, 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 about four sentences and packs in purpose, output shape, q semantics, downstream usage, and pagination rules. It is somewhat dense and could be trimmed, but every sentence carries distinct useful information and the main purpose 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?
With no output schema, the description compensates by specifying the return shape, row contents, nested user object, pagination fields, and casing difference. It gives the agent everything needed to call the tool correctly and use the results, making it very complete for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds real meaning: q is the only name-or-email-to-user_id lookup, it matches case-insensitively before paging, and the cursor parameter is tied to the camelCase nextCursor return field. This goes beyond the schema's basic property descriptions.
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 opens with a specific verb and resource: 'List the people in this organization.' It clearly distinguishes this list tool from member__get and team__list by emphasizing that each row carries membership roles, teams, and user identity, and that it is the org-wide membership listing 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?
It explicitly explains when to use q for name/email lookup and frames the tool as the source of user_id for every member.* operation plus team.add_member/remove_member. However, it does not explicitly say 'use member__get when you already have the user_id,' so the when-not guidance is slightly incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview what removing a member would break, without changing anything: their personal connections and, per connection, which toolboxes reference it and whether that reference reaches beyond the member. Any connection marked needs_resolution will make member.delete refuse. Separately, delegated_entries lists entries on OTHER members’ toolboxes whose pin currently rides on THIS member’s own "use" grant, not their ownership (docs/access-model.md §6) — non-blocking, and member.delete never refuses over it, but say so: once the member is gone those entries go unmet for everyone until somebody with their own "use" on the connection re-pins them; there is no operation that does that automatically. synthetic_tools lists the multi-step tools they own, as metadata only (name, description, step_count — never the steps, which are private to their author): those cannot be shared or transferred, so every one of them is deleted when the member is removed, and their presence makes member.delete refuse outright — say what will be lost before proposing a removal. toolboxes and templates list what they own of each, with a bounded shared_with rollup (counts plus at most five named grantees, never the whole grant list) and an entry_count: only a resource’s OWNER can transfer or delete it, so one left behind when its owner goes becomes unmanageable by everybody in the organization forever — a shared one keeps working for its grantees with nobody able to change it, a private one simply becomes unreachable. Their presence also makes member.delete refuse. Returns { user_id, user: { id, name, email }, connections: [{ connection, referenced_by: [...], needs_resolution }], synthetic_tools: [{ synthetic_tool: { id, name, description, step_count, ... }, referenced_by: [...], needs_resolution }], toolboxes: [{ resource_type, id, name, entry_count, private, shared_with: { team_count, user_count, total, preview }, needs_resolution }], templates: [ ...same shape ], delegated_entries: [{ toolbox_id, toolbox_name, entry_id, connector_slug, tool_name, connection_id }] } directly — no envelope, no cursors. Sensitive read: returns records an operator treats as confidential (audit history, credential metadata, offboarding detail). Read-only, but not harmless — do not echo the contents further than needed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The member’s USER id (`usr_…`) from member.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already say read-only, idempotent, and non-destructive, and the description adds substantial behavioral nuance: it is 'Read-only, but not harmless', warns that data is sensitive and should not be echoed, explains exact refusal triggers, clarifies that delegated entries cannot be auto-fixed, and discloses response-shape details like 'no envelope, no cursors.' This goes well beyond what the annotations provide.
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 long but the domain is genuinely complex and every major section contributes necessary offboarding semantics: connections, delegated entries, synthetic tools, toolboxes/templates, return shape, and sensitivity. It front-loads the core purpose. Some repetition of the 'makes member.delete refuse' pattern could be tightened, but overall the length is earned 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 supplies a full return shape, including resource-specific fields and caveats. It covers blocking vs non-blocking conditions, ownership consequences, shared_with preview bounds, privacy limits on synthetic tool steps, and sensitive-read warnings. The agent has everything it needs to call the tool correctly and interpret its result responsibly.
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 fully documents the single parameter: 'The member’s USER id (`usr_…`) from member.list.' Since schema description coverage is 100%, the description does not need to add parameter-level detail. The tool description adds contextual meaning about what the preview returns for that member, but it does not need to add syntax or format information 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 opens with a specific, informative purpose: 'Preview what removing a member would break, without changing anything.' That is a clear verb+resource+outcome, and the distinction from a real destructive delete is made concrete by explaining which conditions make member.delete refuse. It is easily distinguished from member.get/member.list and other siblings.
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 establishes clear context: this is the pre-removal preview tool, and it explains when refusal will or will not happen ('Any connection marked needs_resolution will make member.delete refuse', 'delegated_entries ... non-blocking', 'synthetic_tools ... makes member.delete refuse outright'). It gives practical guidance such as 'say what will be lost before proposing a removal.' It does not explicitly name an alternative tool or state 'use instead of X', but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the single role one member holds. A member holds exactly ONE role in an organization, so this is a WHOLESALE REPLACE: role_ids must be an array of exactly one role id, and that role becomes their entire access. There is no way to add a role alongside an existing one — "also give Bob the admin role" means Bob stops being whatever he was and becomes an admin, so confirm that with the user before calling. If they need a mix of two roles’ permissions, the answer is a custom role holding both (role.create), not two assignments. Resolve role ids with role.list first. Takes effect on the member’s next request. You cannot assign a role that carries a permission you do not hold yourself, and you cannot re-role a member who holds permissions you lack. Returns the updated membership, including user: { id, name, email }, so you can confirm out loud whose role changed. To change what a role means for everyone who holds it, use role.update instead; to remove the person from the organization entirely, member.delete. NOT CALLABLE FROM ANY AI SURFACE, in-app agent or MCP: handing somebody a role needs step-up reauthentication (confirming it is really you), which neither surface can ask for, so every call from here is refused. Say what needs doing and tell the user to do it in Settings → People in the Elaichi app.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The member’s USER id (`usr_…`) from member.list. | |
| role_ids | Yes | Exactly one role id (`role_…`, from role.list). It replaces the member’s current role; a member cannot hold two. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (all false). The description compensates fully: explains replace semantics, effect on next request, permission constraints (cannot assign roles with permissions you lack), re-role restrictions, return value, and the critical fact that it is NOT callable from AI surfaces due to reauthentication. No contradiction with 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?
While lengthy, every sentence adds critical information: main purpose, constraints, alternatives, prerequisites, effects, return value, and the not-callable warning. The structure is logical and front-loaded with the core purpose. 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?
For a complex tool with security and semantic nuances, the description covers all necessary context: what, when, why not, how, prerequisites, side effects, and return value. Nothing an agent needs to know 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%, but the description adds significant meaning: role_ids must be exactly one and replaces the existing role, and id must come from member.list. It also advises resolving via role.list. This goes beyond the schema's simple descriptions.
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 opens with a specific verb+resource: 'Set the single role one member holds.' It immediately clarifies it's a wholesale replace and differentiates from role.update and member.delete. This is unambiguous and distinguishes it from siblings.
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 when-to-use, when-not-to-use with alternatives: custom role for mixed permissions, role.update for changing role meaning, member.delete for removal. Also instructs to resolve role ids via role.list and to confirm with the user before calling. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read this organization’s own record: id, name, slug, plan and the non-secret settings object. Returns that object directly — no envelope, no cursors. Billing identifiers and trial fields are never included. Takes no arguments; the organization is fixed by the caller’s credentials, so there is no way to read a different one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds meaningful behavioral details: 'Returns that object directly — no envelope, no cursors,' and 'Billing identifiers and trial fields are never included.' It also explains the fixed-by-credentials property, which is not inferable from the schema or 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?
Three sentences, each carrying a distinct purpose: returned fields, return format and exclusions, and parameter/scope constraint. It is front-loaded with the core purpose and contains 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?
For a zero-parameter, read-only tool with no output schema, the description covers the returned fields, exclusions, return envelope, and scope. It gives an agent everything needed to call it correctly and interpret the result, despite not mentioning error 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?
With zero parameters and 100% schema coverage, the baseline is already high. The description adds value by explaining why no arguments are needed ('the organization is fixed by the caller’s credentials'), making the empty parameter schema meaningful rather than accidental.
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 ('Read this organization’s own record') and lists the exact fields returned (id, name, slug, plan, non-secret settings). It also clarifies scope by noting the organization is fixed by credentials, differentiating it from sibling getters like team__get and member__get.
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 clearly scopes the tool to the caller's own organization and explicitly states 'there is no way to read a different one,' which is a when-not condition. However, it does not name alternative tools for reading other resources, so it falls just short of the top tier that requires explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The complete catalog of permission strings a role can grant, each with a human label and description. This is the ONLY legal source of values for role.create and role.update — names not in this list are rejected. Returns { result: [{ name, label, description, group }] } — group is the heading the settings UI files that permission under, useful for grouping them in an answer — and nothing else: no nextCursor, no prevCursor, and limit/cursor are ignored because the whole catalog is one short response.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Accepted for call-shape compatibility and ignored — this operation does not page. Honest here, and only here: the permission catalog is a fixed, static list of a few dozen entries that no organization can grow, so one response really is all of it. | |
| cursor | No | Accepted for call-shape compatibility and ignored — this operation does not page. Honest here, and only here: the permission catalog is a fixed, static list of a few dozen entries that no organization can grow, so one response really is all of it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses non-obvious behavior: limit and cursor are ignored, there is no pagination, the response is 'one short response,' and the catalog is a fixed static list. It also specifies the exact return shape, which matters because there is no output 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 dense but every sentence earns its place: purpose, legal-source status, return shape, and non-pagination are all stated without repetition. The only minor awkwardness is 'the settings UI files that permission under,' but it does not undermine clarity.
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 tool with zero required parameters, strong annotations, and no output schema, this description is complete. It explains what the tool returns, why pagination is irrelevant, and how the results relate to role creation/update. An agent has everything needed to invoke 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%, and the schema already fully explains that limit and cursor are accepted for compatibility and ignored. The description reinforces this but does not add new parameter-level meaning beyond what the schema provides, so the 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 states a specific purpose: it is 'the complete catalog of permission strings a role can grant,' returning each with a human label, description, and group. This clearly distinguishes it from sibling list tools (e.g., connection__list, role__list) and positions it as the reference source for permission values.
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 this is 'the ONLY legal source of values for role.create and role.update — names not in this list are rejected.' This tells the agent exactly when to consult this tool and that no alternative source is valid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one role by id, including its complete permission list. Read this before role.update, whose permissions field replaces that list wholesale. Returns the record directly, or null when the id is unknown — an unknown id is not an error here, so null means "no role has that id", never "the call failed".
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Role id (`role_…`) from role.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds crucial null-return semantics that annotations cannot convey, ensuring the agent does not misinterpret unknown ids as errors.
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 with no redundancy. The core purpose is front-loaded, and the behavioral caveat about null is concise yet complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter, the description covers purpose, usage guidance, and return semantics. The lack of output schema is mitigated by the clear statement that the record is returned directly and permission list is included. Nothing needed 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 description coverage is 100% and the parameter 'id' is fully described in the schema (including the format 'role_…'). The description does not add additional parameter-specific meaning beyond what the schema already provides, 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?
States a specific verb ('Read'), resource ('role by id'), and scope ('complete permission list'). It also distinguishes from role.update by noting the wholesale replacement, clearly separating it from the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises reading this before role.update and clarifies the null behavior ('null means no role has that id, never the call failed'). This gives clear context for when to use and what to expect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the organization’s roles: id (role_…), name, description and the exact permission strings each one grants. This is the lookup you need before member.set_roles, and the way to see what a role currently means before role.update. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Page by sending nextCursor back as cursor until it is null.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page, 1–200 (default 50). Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond these: the exact return shape, the camelCase naming difference from the REST API, and the pagination loop (send nextCursor back as cursor until null). This is valuable operational detail an agent needs.
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 four sentences, each earning its place: first sentence defines the output, second gives use cases, third states return shape and naming caveat, fourth explains pagination. It is front-loaded with the core purpose and contains 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?
For a read-only list tool with no output schema, the description is complete: it states the output shape, pagination mechanics, termination condition, and the intended callers. Nothing an agent needs to successfully invoke the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters, including that cursor is an opaque value taken from a previous call's nextCursor and that limit is clamped. The description's pagination note ('sending nextCursor back as cursor') reinforces but does not add information 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 uses a specific verb ('List') and resource ('the organization's roles'), and enumerates the exact fields returned: id, name, description, and permission strings. It also references sibling tools (member.set_roles, role.update), making the tool's distinct purpose clear without needing to open 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?
The description explicitly states when to use this tool: 'This is the lookup you need before member.set_roles, and the way to see what a role currently means before role.update.' This provides clear context but stops short of naming exclusion cases or contrasting with the sibling role__get tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Author a new multi-step Elaichi tool: a named input_schema plus a DAG of steps, each calling one tool on one of YOUR OWN usable connections. Every step needs connection_id, tool_name and a JSONata args_template over { input, steps } — args_template must PARSE here but is not evaluated until synthetic_tool.execute, so a template that references a field the input_schema never declares still saves clean. depends_on orders the DAG; independent steps run in parallel at execute time. The whole definition is validated as one unit before anything saves — duplicate/unknown/cyclic step keys, bad JSONata, an input_schema whose type is not "object", an unknown connection, an unknown tool on that connection's connector, or a connection you cannot at least "use" (docs/access-model.md §6) all reject the call and save nothing. Name is sanitized into a lowercase_underscore MCP tool identifier and must be unique in the organization (a collision after sanitizing is a conflict, not a silent rename) — read back the returned name, which may differ from what you sent. You become this tool's OWNER, which is permanent: nothing here or elsewhere transfers a synthetic tool to somebody else, and no permission ever widens who may read, edit, execute or delete it beyond you (synthetic_tool.get/.execute/.update/.delete). Pin the created id into a toolbox with toolbox.set_entries (entry type: "synthetic") to make it runnable by anyone the toolbox is shared with — at that point THEIR calls still run under YOUR connection authority, never theirs. Returns the created record, the same shape synthetic_tool.get returns.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name — sanitized server-side into a lowercase_underscore MCP tool identifier. Must be unique in the organization after sanitizing. | |
| steps | Yes | The COMPLETE step list — WHOLESALE REPLACE on update, never a merge. At least one step; every step key must be unique and dependency-free of cycles. | |
| description | Yes | What this tool does — becomes the advertised tool description wherever it is pinned. | |
| input_schema | No | JSON Schema (type "object" or omitted) describing the arguments a caller of this tool must supply — this is what synthetic_tool.execute's `input` is checked against, and what steps' args_template reads as `input.<field>`. Omit for no declared inputs. | |
| output_template | No | Optional JSONata over { input, steps } shaping the final result. Omit for the default output — the object of every step's raw result, keyed by step key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations (which are all false) to disclose critical behaviors: the tool validates the entire definition before saving, rejects invalid inputs, sanitizes names, enforces uniqueness, and grants permanent ownership. It also warns that args_template is parsed but not evaluated, and explains the implications of using connections (delegation). These are important facts that an agent needs to know to avoid errors.
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 dense but each sentence earns its place. It is organized logically, starting with the core action, then validation rules, naming, ownership, and usage context. Though long, it is front-loaded with the most critical information (what the tool does) and avoids fluff. A slightly tighter structure could improve readability, but overall it's effective.
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 high complexity (multiple steps, connections, JSONata, validation rules) and that there is no output schema, the description covers all essential aspects: what it creates, how steps are defined, validation rules, naming, ownership, and follow-up steps. There are no critical gaps that would leave an agent guessing.
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 describes each parameter in detail. The description adds value by explaining how the parameters interact (e.g., steps' args_template reads from input and steps, depends_on orders the DAG) and providing context on the input_schema's relationship to execution. This supplementary context enhances the schema's clarity.
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: authoring a new multi-step synthetic tool with a named input_schema and a DAG of steps. It uses specific verbs ('Author a new multi-step Elaichi tool') and identifies the key resources (input_schema, steps, connections, tools). It is distinct from siblings like update (which modifies existing tools) and execute (which runs them), so an agent can easily tell them apart.
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 (to create a new synthetic tool) and implies when not to (use update for existing tools). It also instructs agents to pin the created tool into a toolbox to make it runnable, and mentions using connection.list_tools for tool names. This helps the agent select the correct sibling and follow the right workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a saved multi-step Elaichi tool. Its steps call real third-party connections, so this has the same real-world, possibly irreversible side effects as toolbox.execute — with several actions per call. input must satisfy the tool’s own input_schema from synthetic_tool.get. Only the tool’s OWNER may run one — and ownership is the gate on every other synthetic-tool operation too (read, edit, delete): no permission reaches somebody else’s. Returns the tool’s mapped output on success; a failing step returns an error naming that step, and steps that already ran are not rolled back. Use toolbox.execute for a single provider tool.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Synthetic tool id (`syn_…`) from synthetic_tool.list. | |
| input | Yes | Arguments matching the tool’s own input_schema (synthetic_tool.get). Required — send {} when it declares no inputs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only offering readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, the description carries the behavioral burden and meets it. It discloses real-world side effects across several actions, irreversible risk, no rollback of already-run steps, and the error shape on failure—none of which are in 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 dense but every sentence contributes: purpose, side-effect warning, input requirement, ownership gate, return/error behavior, and sibling alternative. Important caveats are front-loaded before the ownership and routing details, with no filler or tautology.
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-step execution tool with no output schema, the description is unusually complete: it covers success and failure output, side effects, rollback behavior, permission requirements, input validation source, and the correct alternative tool. An agent has the information needed to invoke and interpret the call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters at 100% coverage, including the syn_ id source and the instruction to send {} for empty inputs. The description repeats that input must satisfy the tool's own input_schema, adding no new parameter-level meaning beyond the structured schema, so the high-coverage 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?
The description opens with a specific verb and resource: 'Run a saved multi-step Elaichi tool.' It goes beyond a generic label by naming the execution action and immediately distinguishes itself from toolbox.execute ('Use toolbox.execute for a single provider tool'), so an agent can separate execution from the synthetic-tool CRUD siblings.
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 clear context for when this tool applies—running a saved multi-step synthetic tool—and explicitly names the alternative for single provider tools. It also states a hard prerequisite: the caller must be the tool's owner, and notes this permission rule is consistent across all synthetic-tool operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one synthetic tool, including the input_schema its caller must satisfy and the steps it runs. Returns the record directly. OWNER-ONLY: a caller who does not own the tool gets a 404, not a permission error, even holding toolbox:view or toolbox:manage — not being allowed to see a tool and the tool not existing are deliberately indistinguishable, so never report a 404 here as proof the id is wrong. There is no visibility parameter on this operation or on GET /synthetic-tool/:id: a synthetic tool’s body is the most private thing the product stores about a member (the ids of connections nobody else can see, literal args_template text, the output JSONata), and no permission opens it. Reading one is also not permission to RUN it: synthetic_tool.execute needs the same ownership. Read this before synthetic_tool.execute — the input schema is author-defined and cannot be guessed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Synthetic tool id (`syn_…`) from synthetic_tool.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral context beyond them: non-owners receive a deliberate 404 indistinguishable from a missing tool, there is no visibility parameter, the body is the most private member data stored, and reading is separate from running. This is exactly the kind of non-obvious behavior an agent needs to reason correctly.
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 longer than a typical get operation, but each sentence carries meaningful operational guidance: the 404 ambiguity, the privacy rationale, the separation of read vs execute, and the ordering instruction. It is front-loaded with the core purpose. It loses one point because some phrasing is redundant and could be tightened without losing 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?
For a single-parameter read operation with no output schema, the description provides everything an agent needs: what the record contains, how to obtain the id, the ownership restriction, the deliberately misleading 404, and the recommended call order relative to synthetic_tool.execute. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single `id` parameter at 100% and explains it is a `syn_…` id from synthetic_tool.list. The description adds little new meaning about what the parameter is, instead focusing on auth and 404 semantics. Per the baseline rule for high schema coverage, a 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 opens with a specific verb and resource: 'Read one synthetic tool', and states exactly what the read returns (the input_schema, the steps it runs, and the record directly). It also implicitly distinguishes itself from synthetic_tool.list by saying 'one' tool, and from synthetic_tool.execute by noting that reading is not permission to run. This leaves no ambiguity about what the tool does.
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 explicit guidance on when to call this tool: 'Read this before synthetic_tool.execute — the input schema is author-defined and cannot be guessed.' It also tells the agent when not to treat results as expected by explaining the ownership 404 behavior and that reading does not grant execution rights. This is strong routing guidance relative to its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List synthetic tools: multi-step tools defined inside Elaichi — a named input schema over a chain of connector calls — as opposed to the provider tools that come from a connection. Ids are syn_…. Reading and executing are two different gates here, so never infer one from the other. READING: OWNER-SCOPED, and no permission widens it. A synthetic tool carries no ACL — there is nothing to be "shared with me" — so this is exactly the caller’s own tools; toolbox:view and toolbox:manage add nothing, here or on GET /synthetic-tool, so this cannot answer "how many synthetic tools does the organization have" and must not be reported as if it could. A tool missing from this list may therefore mean "not yours" rather than "does not exist" — and synthetic_tool.get answers a tool you may not read with a 404 for the same reason. EXECUTING is no wider: only the tool’s OWNER may run one, because a synthetic tool’s steps run over the owner’s own connections with no re-check at execution. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Unlike the other lists in this catalog limit defaults to 200 rather than 50, so one call is the entire set for almost every organization. It is still a PAGE: a non-null nextCursor means there are more rows, and the only way to reach them is to send it back as cursor until it comes back null. A page whose nextCursor is not null is never a total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page, 1–200. Defaults to 200 — the whole set in one call for almost every organization — rather than the 50 the other lists here default to. Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare read-only and idempotent hints, but the description adds essential context: owner-only scoping, no ACL broadening, separate read/execute gates, camelCase return shape, and detailed pagination semantics. No contradiction with 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?
Well-organized, front-loaded, and almost every sentence adds new information. It is slightly verbose and repeats the 'not a total page' point, while also duplicating a little of the schema's limit description, keeping it just below a perfect conciseness score.
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?
Complete for a list tool with no output schema: it documents the return fields, pagination loop, default page size, and how absence of a row should be interpreted. An agent has everything needed to call it correctly and to avoid overclaiming from missing results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters at 100%, and the description adds real semantic value: limit's 200 default is a page-size choice, larger values are clamped, and cursor must be taken verbatim from nextCursor and sent back until null. This meaningfully exceeds the schema's bare parameter documentation.
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 the action and resource precisely: 'List synthetic tools', defines them as multi-step tools with `syn_…` ids, and explicitly contrasts them with provider tools from connections. This distinguishes it from sibling tools like connection__list_tools and synthetic_tool__get/execute without ambiguity.
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 conditions for use: the list is owner-scoped, cannot answer org-wide counts, and must not be reported as such. It also warns not to infer execution rights from read access and mentions synthetic_tool.get's 404 behavior, giving the agent clear when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a synthetic tool's definition — name, description, input_schema, steps or output_template. MERGE at the top level: fields you omit keep their current value. Sending steps is a WHOLESALE REPLACE of the step list, same as toolbox.set_entries — resend every step you want to keep, not only the ones you changed. The merged definition (your patch layered over what is stored) is re-validated as a whole exactly as synthetic_tool.create validates a new one, so an unrelated field edit can still fail if it leaves the stored steps inconsistent with a new input_schema. A step whose (connection_id, tool_name) pair is unchanged from what is already stored rides forward without re-checking your access to that connection — protects an honest read-modify-write from being refused by a restriction written after the step was first saved — but any step that is new, or that changes tool_name while keeping connection_id, is validated fresh against your CURRENT access and restrictions. OWNER-ONLY, same as every other synthetic-tool operation: this needs toolbox:create or toolbox:manage to call at all (the coarse permission gate PATCH /synthetic-tool/:id enforces), but that permission is not the real gate — unlike toolbox.update, a toolbox:manage holder who does not own this tool still gets the exact same 404 an unknown id gets, never access. Read synthetic_tool.get first: this endpoint does not tell you what changed, only the result after. Returns the updated record, the same shape synthetic_tool.get returns.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Synthetic tool id (`syn_…`) from synthetic_tool.list. | |
| name | No | New name — sanitized and uniqueness-checked the same as at creation. Omit to leave unchanged. | |
| steps | No | The COMPLETE step list — WHOLESALE REPLACE on update, never a merge. At least one step; every step key must be unique and dependency-free of cycles. | |
| description | No | New description. Omit to leave unchanged; unlike toolbox.update this cannot be cleared to null — it is always required text. | |
| input_schema | No | Replacement input_schema. Omit to leave unchanged. | |
| output_template | No | Replacement output_template, or null to clear it back to the default output. Omit to leave unchanged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-readonly, non-idempotent, non-destructive operation, but the description adds critical behavioral detail: top-level merge vs wholesale steps replacement, full re-validation, the nuanced access-control rule (owner-only, with a toolbox:manage holder getting a 404 if not the owner), and the step-riding-forward exception. This far exceeds what annotations 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?
Though long, every sentence carries essential information. The structure front-loads the purpose, then merge semantics, steps replacement, validation, and access control in a logical order. There is no redundancy or filler; the density is justified by the tool's 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?
With no output schema, the description explicitly states the return shape ('the same shape synthetic_tool.get returns') and points the agent to read get first. It covers merge behavior, validation, access control, and steps replacement, leaving no gap an agent would need to guess about for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the schema: it clarifies the MERGE behavior at the top level, that steps is a wholesale replace (and to resend every step), and that validation can fail due to unrelated field edits. These are critical nuances not present in 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?
States a specific verb ('Edit') and a specific resource ('synthetic tool's definition') and enumerates the exact fields it operates on. It also differentiates from related tools by contrasting with synthetic_tool.create and toolbox.update, making the purpose 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 instructs the agent to read synthetic_tool.get first and explains why (the endpoint only returns the result, not what changed). It also contrasts with toolbox.update regarding ownership and permission semantics, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an existing organization member to a team. This does not invite anyone: the person must already be a member (member.list). Anything shared with the team — toolboxes, connections — becomes available to them immediately. Returns the TEAM record, in the same shape team.get returns and with membership already re-read, so member_count includes the person you just added; it does not return a membership record, because there is no such thing.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes | Team id (`team_…`) from team.list. | |
| user_id | Yes | The person’s USER id (`usr_…`) from member.list — not a membership id, and not an email address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It goes beyond the annotations by explaining the immediate side effect: 'Anything shared with the team — toolboxes, connections — becomes available to them immediately.' It also describes the exact return shape (TEAM record like team.get, with member_count refreshed) and explicitly notes it does not return a membership record. This is substantial behavioral disclosure for a mutation with only false hints in 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 three dense sentences with no filler. Each clause earns its place: the core action, the non-invite caveat, the immediate accessibility consequence, and the return format. It is front-loaded with the verb and object.
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 only two required parameters, a complete input schema, and no output schema, the description covers the key operational facts: preconditions, side effects, and return semantics. The only information an agent might want but is absent is duplicate-add behavior, which is minor. Overall the definition is 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 input schema already fully documents both team_id and user_id, including the user_id format constraint, so the baseline is 3. The description reinforces that user_id refers to an existing member and references member.list for ID lookup, but doesn't add material format or meaning beyond the schema. It is adequate but not a major compensation for a coverage gap because there is no gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Add' with a precise object: 'an existing organization member to a team.' It immediately distinguishes itself from invitation workflows by stating 'This does not invite anyone,' and clarifies this is a membership operation rather than a creation or invitation tool. This clearly separates it from siblings like invite__create and team__create.
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 provides an explicit precondition: the person 'must already be a member (member.list),' and tells the agent where to get the relevant IDs. It also states the operation's scope boundary — 'does not invite anyone' — so an agent won't use it for invitations. It lacks a named alternative tool, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an empty team. Only name is required. Returns the created team including its new team_… id. Nobody is added by this call — add people one at a time with team.add_member.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name of the new team. | |
| description | No | Optional free-text description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-idempotent, non-destructive creation operation. The description adds useful context beyond that: the team is created empty, no members are added, and the response includes the newly generated `team_…` id. This meaningfully clarifies the tool's behavior without contradicting 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?
Three short, purposeful sentences with no filler. The most important facts are front-loaded: create an empty team, only name is required, returns the new team id, and no members are added. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter creation tool with no output schema, the description is complete: it states the required input, the side-effect boundary (empty team, no members), and the return value including the id. Sibling routing is also addressed, so 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 the schema fully documents both parameters (`name` and `description`). The description adds only the requirement that `name` is mandatory and the return contains the new team id, providing marginal extra meaning but not compensating for any schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create'), a specific resource ('team'), and a precise scope ('empty team'). It also distinguishes itself from team.add_member by clarifying that no one is added during creation, which helps an agent tell this apart from sibling 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 explicitly explains when to use this tool ('Create an empty team') and points to the alternative for adding people ('add people one at a time with team.add_member'). It also notes that only `name` is required, preventing unnecessary parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one team. Returns the record directly — no envelope, no cursors — or null when the id is unknown. The record carries member_count/admin_count and a BOUNDED preview of the roster (member_preview_user_ids, admin_preview_user_ids — at most five ids each), never the whole membership: a team can hold thousands of people. Alongside the preview, members repeats those same few as { id, name, email }, so you can name them without a second call; a previewed id with no members entry has left the organization. There is no operation for the full roster — say what member_count is rather than implying the preview is everyone.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Team id (`team_…`) from team.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnly, idempotent, non-destructive, but the description adds substantial behavioral detail: null on unknown id, bounded roster previews, at most five ids, duplicate members entries, stale ids meaning departed users, and the absence of any full-roster operation. This goes well beyond the annotation basics.
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 detailed but every sentence earns its place by explaining return format, preview limits, member name resolution, stale-member behavior, and a critical usage warning. It is front-loaded with the core purpose and structured to avoid ambiguity.
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 must carry the full interpretative burden, and it does: it explains the return shape, null behavior, bounded preview semantics, member_count/admin_count, and the no-full-roster limitation. An agent has everything needed to call this tool and correctly interpret its result.
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 single parameter has 100% schema coverage with a helpful description ('Team id (team_…) from team.list'), so the schema carries the parameter meaning. The tool description only adds behavior on unknown ids, not new parameter-level semantics, 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?
Opens with 'Read one team,' a specific verb plus resource, and further distinguishes itself by describing the exact return shape: direct record, no envelope or cursors, and null for unknown ids. The singular scope clearly separates it from team__list and other team operations.
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?
States clear scope: reading a single team by id, and clarifies that there is no full-roster operation, telling the agent to rely on member_count rather than implying the preview is complete. It does not explicitly name an alternative like team__list, but the context makes the singular-versus-list distinction evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the organization’s teams: id (team_…), name, description and member count. q filters by team name before paging. Who belongs to a team is not in these rows — read one with team.get. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Page by sending nextCursor back as cursor until it is null.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Case-insensitive substring of the team name, applied before paging. Matches team names only, never member names. | |
| limit | No | Rows per page, 1–200 (default 50). Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it explains the camelCase naming convention (differing from the REST API), describes the pagination flow (sending nextCursor back as cursor), and notes that q filters before paging. These are not in the annotations and are crucial for correct invocation. No contradiction with readOnlyHint, idempotentHint, or destructiveHint.
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 front-loaded with the purpose, then efficiently covers pagination, naming, and the caveat about membership. Each sentence adds value, and there is no fluff or redundancy. It is concise yet comprehensive.
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 list tool with no output schema, the description covers the return shape, pagination mechanism, filtering behavior, and explicitly points to a sibling for a related need. Nothing essential is missing for an agent 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 coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal new semantic meaning for parameters; it reinforces the q filter behavior and cursor usage, but these are largely restatements of the schema. 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 states a specific verb and resource: 'List the organization’s teams' and enumerates the fields returned. It also distinguishes itself from team.get by explicitly noting that team membership is not included, which separates it from a sibling 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?
It clearly implies this is the tool for listing teams and directs users to team.get for membership details. However, it does not explicitly contrast with other list tools (e.g., member.list) or state when not to use it, so it lacks explicit exclusions beyond the team.get reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Appoint or remove a TEAM administrator — the per-team counterpart of the org-wide team:manage permission. is_admin: true gives this person add/remove-member, rename and describe rights over THIS team only; is_admin: false demotes them back to an ordinary member with no such rights. The person must already be on the team (team.add_member first) — this does not add them, and it 404s if they are not already a member. Refuses if you try to appoint YOURSELF (self-promotion) — the same self-escalation guard team.add_member enforces; demoting yourself is allowed. Appointing a team admin does not widen what they can see or use — it only lets them manage who else is on this one team — and it never reaches team.delete, which stays org-wide-team:manage-only regardless of who administers the team. This operation itself needs org-wide team:manage to call, the same narrower gate its REST route enforces: unlike team.add_member/team.remove_member, an existing team administrator with no org-wide team:manage cannot use this op to promote or demote anyone on their own team. Returns the TEAM record, the same shape team.get returns.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes | Team id (`team_…`) from team.list. | |
| user_id | Yes | The person’s USER id (`usr_…`) from member.list — not a membership id, and not an email address. | |
| is_admin | Yes | true appoints this person a team administrator of THIS team — they gain add/remove-member, rename and describe rights over it, scoped to this one team. false demotes them back to an ordinary member. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate readOnly=false and similar flags; the description adds critical behavioral context: self-escalation guard, no membership addition, no visibility widening, no team.delete access, and required auth level. It goes well beyond structured annotations and does not contradict them.
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 mostly front-loaded: first sentence states purpose and contrasts the org-wide scope. Each subsequent sentence earns its place by listing a prerequisite, guard, scope, auth requirement, or return shape; minor redundancy around 'same narrower gate' prevents a 5.
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?
Complete for a rights-mutation tool: prerequisites, failure modes, permission gate, scope limitations, and return shape (same as team.get) are all stated. No output schema exists, so naming the return shape is important and handled.
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?
Input schema covers all params at 100%, so the baseline is 3; the description adds meaning by explaining exactly what is_admin true/false grants (add/remove-member, rename, describe rights) and that user_id must be an existing member. It doesn't add new format details for team_id/user_id, hence 4 rather than 5.
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 explicit verb 'Appoint or remove' and resource 'TEAM administrator,' then scopes it as 'per-team counterpart' to org-wide team:manage. It distinguishes itself from team.add_member/remove_member and team.delete, so an agent can infer what this operation is and isn't.
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 explicit prerequisites: target must already be a member via team.add_member, otherwise the tool 404s. It also states when the operation will refuse (self-promotion) and names the required permission (org-wide team:manage), contrasting with sibling team.add_member/team.remove_member.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a team or change its description. MERGE, not replace: fields you omit keep their current values (unlike member.set_roles, role.update’s permissions and toolbox.set_entries, which all replace wholesale). Membership is untouched — use team.add_member / team.remove_member for that. Returns the updated team record, the same shape team.get returns.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Team id (`team_…`) from team.list. | |
| name | No | New name. Omit to leave unchanged. | |
| description | No | New description. Omit to leave unchanged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-idempotent, non-destructive operation, but the description adds important behavioral context: the update is a MERGE, omitted fields retain current values, and membership is untouched. It also discloses the return shape by pointing to team.get. This goes beyond what annotations alone 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?
The description is tight and front-loaded: purpose first, then merge semantics and exclusions, then return value. Every sentence earns its place by either clarifying behavior or routing to alternatives. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter update tool, the description covers the operation, the merge behavior, what is intentionally not touched, and the return value shape. There is no output schema, but the description compensates by referencing team.get's response shape. Nothing needed to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes each parameter completely, and the description reinforces the key semantic distinction that omitted fields are preserved. This is valuable because it explains the behavioral meaning of omitting parameters, which the schema only hints at with 'Omit to leave unchanged.' The description adds usable guidance beyond the raw field definitions.
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 identifies a specific verb and resource: 'Rename a team or change its description.' It distinguishes itself from related tools by explicitly contrasting merge semantics with replace-style tools and by directing membership operations to team.add_member/team.remove_member. An agent can unambiguously determine what this tool does and what it intentionally does not do.
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 explicit when-to-use and when-not-to-use guidance: use it for renaming or description changes, and use team.add_member/team.remove_member for membership changes. It also warns against assuming replace semantics by naming sibling tools with wholesale replacement behavior. This fully routes an agent to the correct tool context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a template: a named, shareable group of tool references with NO connection attached — other people (or the caller) later stamp their own connections into a toolbox from it (toolbox.create with template_id). entries is optional — create an empty one and fill it later with template.set_entries. Each proxy entry needs connector_slug + tool_name (never connection_id — that only exists after stamping), and frozen_params pins argument values callers cannot override. Take tool names from connection.list_tools, which is already filtered by the restrictions that apply here: entries are validated as a set, so one bad name rejects the whole call. shares grants access at creation time — see template.share for the level ladder; sharing a template exposes only tool NAMES and pinned parameters, never a connection, so (unlike toolbox.create) there is nothing to warn about. Returns the created template including its new tpl_… id.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name of the new template. | |
| shares | No | Grants to create alongside the resource. Omit, or send [], for a private one. | |
| entries | No | The COMPLETE entry list. Whatever you send replaces every existing entry; entries you omit are deleted. | |
| description | No | Optional free-text description shown to people it is shared with. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
All annotations are false, so the description carries the full burden, and it delivers substantial behavioral context: templates have no connection attached, entries are validated as a set so one bad name rejects the whole call, frozen_params pins values callers cannot override, and sharing exposes only names and pinned parameters, never a connection. It also states the return value including the new tpl_… id, which is critical since there is no output 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 a single dense paragraph, but every sentence adds value and the key fact is front-loaded. It could be trimmed slightly without losing information, but the length is justified by the number of non-obvious behaviors and cross-tool references the agent needs.
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, the complete schema, and the absence of an output schema, the description covers everything needed: the template concept, the no-connection rule, entry validation behavior, sharing semantics, related alternative tools, and the return value. No essential operational detail appears to be 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?
With 100% schema description coverage the baseline is 3, but the description adds meaning beyond the schema: it explains that entries can be omitted and filled later, that proxy entries require connector_slug + tool_name (never connection_id), that tool names should come from connection.list_tools, and that shares grants access at creation time. These clarifications materially improve correct parameter selection.
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 opens with 'Create a template' and immediately defines precisely what a template is: a named, shareable group of tool references with no connection attached. It also contrasts this with toolbox.create, clarifying the resource and scope unambiguously and distinguishing the tool from siblings like template.update, template.share, and toolbox.create.
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 explicit when-to-use guidance: it says entries is optional and can be filled later with template.set_entries, advises sourcing tool names from connection.list_tools, points to template.share for the sharing-level ladder, and explicitly contrasts with toolbox.create ('unlike toolbox.create there is nothing to warn about'). An agent can route correctly without guessing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one template definition and its entries. Returns a NESTED object — { template: { id, name, description, … }, entries: [...], access } — so the name is result.template.name, never result.name, and the entry list is result.entries; access is the caller’s own level ("owner" | "edit" | "use" | "view") — "use" is what authorizes toolbox.create with this id as template_id. Entries here never carry connection_id: a template pins nothing. Errors when the id is unknown or the caller cannot see it — visible meaning owned by them, shared with them or one of their teams, or shared org-wide, and ONLY that: template:view/:manage does not widen it, there is no visibility parameter here or on GET /template/:id, and an admin auditing the organization reads nothing they were not given. Unlike role.get, team.get and the governance reads, it never answers null, so there is no null to interpret. Always read this before template.set_entries, which replaces entries wholesale.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template id (`tpl_…`) from template.list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and idempotent, but the description adds substantial behavioral detail: the exact nested response shape, the caller's access level, error conditions for unknown or invisible ids, the permission semantics of visibility, and the fact that this tool never returns null. This goes well beyond the annotation baseline.
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 dense but every sentence earns its place. It front-loads the core purpose and return-nesting warning, then covers access levels, error/visibility semantics, null behavior, and the relationship to template.set_entries without repetition. The structure guides an agent from immediate invocation details to edge-case behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description is remarkably complete. It covers return shape, access semantics, permission boundaries, error behavior, and the important workflow of reading before template.set_entries. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single `id` parameter with its format (`tpl_…`) and source (template.list), so the description adds little parameter-level meaning. It mentions using the id as template_id for toolbox.createtons, but that is more about downstream authorization than the parameter itself.
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 opens with a specific verb and resource: 'Read one template definition and its entries.' It clearly identifies this as a single-item read and later contrasts it with role.get/team.get/governance reads, distinguishing it from sibling tools even without seeing their 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?
The description explicitly instructs 'Always read this before template.set_entries,' giving a concrete workflow where this tool is required. It also explains how the returned `access` value ('use') authorizes toolbox.create, and contrasts the null behavior with role.get/team.get so an agent knows when not to expect a null result.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List template DEFINITIONS visible to the caller: their own, plus every one explicitly shared with them, with one of their teams, or with the whole organization — and nothing else. No permission widens it. template:view and template:manage add nothing here, and this cannot answer "how many templates does the organization have". Unlike connections and toolboxes, templates carry no org-wide oversight path at all — not here, not in the REST API, not in the Elaichi web app: an org owner/admin sees a template only when they own it or it has been shared with them, whatever permission they hold. A template is a group of tools with frozen/default params; it NEVER references a connection, so it is not itself runnable — stamp a toolbox from one with toolbox.create (template_id). Ids are tpl_…. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Unlike the other lists in this catalog limit defaults to 200 rather than 50, so one call is the entire set for almost every organization. It is still a PAGE: a non-null nextCursor means there are more rows, and the only way to reach them is to send it back as cursor until it comes back null. A page whose nextCursor is not null is never a total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page, 1–200. Defaults to 200 — the whole set in one call for almost every organization — rather than the 50 the other lists here default to. Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description goes far beyond this by detailing visibility semantics, the fact that templates are not directly runnable, the `tpl_` ID convention, the camelCase return shape vs REST snake_case, and the precise pagination contract including what a non-null nextCursor means.
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 front-loaded with the core purpose and dense with useful distinctions, but it is somewhat long and contains mild redundancy (e.g., 'nothing else', 'No permission widens it', and 'template:view and template:manage add nothing here' all make overlapping points). Still, nearly every sentence contributes actionable guidance.
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 specifying the return envelope ({ result, nextCursor, prevCursor }), the pagination contract, the default page size, and the relationship to other Elaichi concepts. Given the tool's complexity around visibility and paging, nothing essential 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?
Even though the schema covers 100% of parameters, the description adds meaningful semantics: `limit` defaults to 200 rather than 50, larger values are clamped not rejected, `cursor` is opaque and must be copied verbatim from a previous `nextCursor`, and it clarifies how to reach all pages. This materially improves an agent's ability to invoke the parameters correctly.
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 precisely what the tool does: 'List template DEFINITIONS visible to the caller' and defines the exact visibility scope (own, explicitly shared, team-shared, org-shared — and nothing else). This clearly distinguishes it from the many other list tools like toolbox__list and connection__list.
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 explicit when-not-to-use guidance: it cannot answer org-wide template counts, permissions don't widen visibility, and there is no org-wide oversight path unlike connections/toolboxes. It also contrasts the pagination default with other list tools and explains how to page through results, so an agent knows exactly when and how to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a template’s entries: a WHOLESALE REPLACE, never a merge (name and description are untouched — those belong to template.update). The array you send becomes the template’s entire entry list, so "add the Slack tool" means reading template.get, resending its existing entries and appending yours; sending only the new entry deletes everything else. Each proxy entry needs connector_slug + tool_name — never connection_id, which a template cannot carry; frozen_params and enabled are optional. Validate names against connection.list_tools first — the set is validated as a whole, so one bad entry rejects the call and nothing changes. Toolboxes already stamped from this template are UNTOUCHED by this call (stamping copies entries once, it is never a live link). Returns the updated { template, entries } detail.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template id (`tpl_…`) from template.list. | |
| entries | Yes | The COMPLETE entry list. Whatever you send replaces every existing entry; entries you omit are deleted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations that are entirely false and uninformative, the description carries the full disclosure burden. It reveals wholesale replacement, deletion of omitted entries, whole-set validation with atomic failure, the invalidity of connection_id, and that already-stamped toolboxes remain untouched. This is rich, actionable behavioral context 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 long but every sentence earns its place. The critical wholesale-replace semantics are front-loaded, concrete examples illustrate intent, and no sentence is redundant with the schema or 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?
For a 2-parameter tool with nested entry objects and no output schema, the description provides all necessary context: replacement behavior, validation workflow, failure atomicity, side effects on toolboxes, and the return shape. An agent can correctly invoke it without needing additional clarification.
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 the schema covers 100% of parameters, the description adds meaning the schema lacks: it specifies that proxy entries require connector_slug + tool_name, explicitly forbids connection_id, marks frozen_params and enabled as optional, and explains that the entries array is a complete replacement list. These are essential semantics not inferable from the schema alone.
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 opens with a specific verb and resource: 'Replace a template’s entries', then immediately differentiates itself from template.update by noting that name and description are untouched. This makes the tool's purpose unmistakable and distinguishes it from related siblings such as template.update and toolbox.set_entries.
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 explicit operational guidance: to 'add the Slack tool', read template.get, resend existing entries, and append the new one. It also tells the caller to validate against connection.list_tools before sending, and routes name/description changes to template.update. This is clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a template’s name or description (not entries — use template.set_entries). MERGE: fields you omit keep their current values. description takes a string, or null to clear it; any other type is rejected rather than silently wiping the field. Returns the updated { template, entries } detail — the same NESTED shape template.get returns, so the name is result.template.name, never result.name.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template id (`tpl_…`) from template.list. | |
| name | No | New name. Omit to leave unchanged. | |
| description | No | New description; null clears it. Omit to leave unchanged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate this is non-read-only and non-idempotent; the description adds substantial behavior: omitted fields keep their values, null clears description, non-string descriptions are rejected rather than silently wiping, and the return value is nested. This goes well beyond the structured 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?
Three sentences, each carrying essential information: scope, merge/validation behavior, and return shape. The most important distinction is front-loaded, and there is 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?
For a mutation tool with no output schema, the description fully compensates by specifying the nested return shape and how to read it (result.template.name). It also covers validation behavior and the sibling alternative, so nothing critical is left unexplained.
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 already documents each parameter's type and basic behavior. The description adds extra meaning by clarifying merge semantics, null-clearing, and the rejection of unexpected types rather than silent data loss, which earns it above the 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?
The description states the exact action — updating a template's name or description — and explicitly excludes entries, which distinguishes it from the template.set_entries sibling. The verb and resource are specific and unambiguous.
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 names the alternative when entries are involved ('not entries — use template.set_entries'), and explains the merge behavior for omitted fields. An agent can decide when to use this tool without inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a toolbox: a connection-bound, shareable bundle of tool references. Two ways to build one, combinable: pass template_id to STAMP it (copies that template’s entries at creation time — never a live link; needs "use" access to the template) with connection_map filling each stamped proxy entry’s connector from one of the caller’s own usable connections (a connector the map does not name is left "needs connection", not rejected); and/or pass entries for hand-written ones beyond whatever stamping copied, which get full validation including connection_id. name defaults to the template’s name when stamping and is otherwise required. shares grants access at creation time — see toolbox.share for the level ladder; sharing DELEGATES, so every response carries a delegation summary — { connection_count, delegator_count, visible: { connection_count, private_connection_count, preview } } — saying what this toolbox runs on: read it out before you share, not after. Returns { toolbox, entries, delegation } with the new tbx_… id. Not a prerequisite for running tools the caller already has — for that, toolbox.execute against global:{their usr_… id}.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Display name. Required unless template_id is set, where it defaults to the template’s own name. | |
| shares | No | Grants to create alongside the resource. Omit, or send [], for a private one. | |
| entries | No | The COMPLETE entry list. Whatever you send replaces every existing entry; entries you omit are deleted. | |
| description | No | Optional free-text description shown to people it is shared with. | |
| template_id | No | Template id (`tpl_…`) from template.list to stamp from — a one-time copy of its entries, never a live link. Needs "use" access to the template. | |
| connection_map | No | connector_slug -> connection_id (`conn_…`), filling every STAMPED proxy entry of that connector with one of the caller’s own usable connections; the caller becomes that entry’s delegator. A connector this map does not name is left with connection_id null ("needs connection") rather than being rejected. Ignored when template_id is absent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations providing only false hints, the description carries the full burden and does so thoroughly: it reveals that template stamping is a one-time copy, unmapped connectors are left as 'needs connection' rather than rejected, sharing delegates and produces a delegation summary, and it names the exact return shape. This goes well beyond the structured 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 single paragraph is dense and front-loaded with the core definition, and virtually every clause contributes new information. It is long, but justified by the tool's complexity; a bulleted or sectioned layout would be easier to scan but this does not seriously hurt usability.
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?
Despite no output schema, the description states the response shape ({ toolbox, entries, delegation } with tbx_ id) and the delegation summary fields. It covers preconditions (use access on template, caller's own connections), side effects (delegation), and the relationship to toolbox.execute, making the definition complete for a complex create call.
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 schema already documents each parameter; the description adds meaningful cross-cutting semantics for template_id/connection_map (combinable stamping), entries (full validation), and shares (delegation summary and 'read it out before you share'). The extra meaning earns more than the baseline 3, though many parameter details remain correctly delegated to 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?
Opens with a specific verb and resource: 'Create a toolbox: a connection-bound, shareable bundle of tool references.' It explains two construction modes (template stamping and hand-written entries) and closes with an explicit contrast to toolbox.execute, so the agent can distinguish it from the main sibling that might be confused with 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?
Gives concrete when-to-use detail: stamping from template_id, adding entries, and granting shares at creation time. It explicitly says this is not a prerequisite for running tools the caller already has and points to toolbox.execute, but it does not spell out when to prefer create over toolbox.update/set_entries/share for existing toolboxes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one real third-party action through a connection this toolbox reaches — send the Slack message, create the HubSpot contact, read the calendar — with the organization’s restrictions and the approval gate applied. This is the operation that reaches outside Elaichi: it does whatever the underlying provider tool does, and the provider may make it irreversible, so confirm the target and the arguments before calling it. toolbox_id comes from toolbox.list, where global:{the caller’s usr_… id} holds every tool they can run and is the right default; tool_name must match a name returned by toolbox.get for that same id exactly; arguments must satisfy that tool’s own input schema (send {} when it takes none). A STORED toolbox the caller does not own but reaches only via a "use" share still runs — that is delegation: the call executes through the pinning editor’s connection authority, not the caller’s own, and if that authority is later revoked the tool simply disappears from toolbox.get, unmet, rather than failing here. Returns the provider’s raw response, whose shape is defined by the provider, not by Elaichi. Use synthetic_tool.execute instead for a saved multi-step Elaichi tool. The same tools are usually advertised here individually under their own {account}__{tool} names too, or behind search_tools and execute_tool once there are many of them. Those reach the same accounts at the same cost — but they are a SEPARATE namespace, not aliases, so pick one path and stay inside it. This operation’s tool_name must be a name toolbox.get returned for this same toolbox_id; passing an advertised {account}__{tool} name, or one search_tools handed you, fails with a bare "Tool not found: " that says nothing about the namespace being wrong. To use the other paths, call the advertised tool directly by its own name, or pass a search_tools result to execute_tool.
| Name | Required | Description | Default |
|---|---|---|---|
| arguments | Yes | Arguments matching the tool’s own input schema from toolbox.get. Required — send {} for a tool that takes no arguments. | |
| tool_name | Yes | Exact tool name as returned by toolbox.get for that same id. Never invent or reformat it. | |
| toolbox_id | Yes | Id from toolbox.list — `global:usr_…` (everything the caller can run), `connection:conn_…` (one account), or a stored `tbx_…`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnly=false and openWorld=true; the description adds that the provider may make the action irreversible, that approval gates and organization restrictions apply, that delegated calls execute under the pinning editor's authority, and that revocation makes the tool disappear from toolbox.get rather than fail. No contradiction with 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 long but information-dense and front-loaded with purpose and risk. Some caveats around separate namespaces and failure modes could be tightened, but every major sentence adds value for preventing misuse.
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 an open-world execution tool with no output schema, it completely covers identifier sources, targeting rules, delegation auth, failure behavior, namespace pitfalls, and return shape. Nothing needed for correct use 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%, but the description goes beyond schema: it explains how to obtain toolbox_id and identifies the global:{usr_...} default, requires exact name matching against toolbox.get, and clarifies arguments must satisfy the target tool's schema and be {} when none. This materially improves correct invocation.
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 opens with a specific verb and resource: run one real third-party action through a connection the toolbox reaches, with concrete examples (send Slack message, create HubSpot contact, read calendar). It explicitly contrasts with synthetic_tool.execute and the individually advertised tools, so an agent can distinguish it from siblings 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?
It states exactly where toolbox_id comes from, that tool_name must match toolbox.get exactly, and that synthetic_tool.execute is the alternative for saved multi-step tools. It also warns that advertised {account}__{tool} names and search_tools results live in a separate namespace and will fail here, which is strong when-to-use/when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve one toolbox: its own record plus, when the caller’s access reaches "use", exactly what it can execute right now after overrides, restrictions and delegation are applied. Returns a NESTED object — { toolbox: { id, name, description, … }, entries: [...], access, delegation, tools?: [{ name, description, input_schema, … }] } — so the name is result.toolbox.name, never result.name. Entries pinned to a connection carry delegated_by_user_id (whose "use" grant the pin rides on) and, when resolvable, unmet/tool_available/delegation_ok/connection_status. delegation is the bounded summary of what this toolbox RUNS ON — answer "what does it run on?" from it rather than by counting entries[].connection_id, which misses every synthetic entry, since those pin nothing of their own and their tool’s steps hold the connections. tools is present only when access reaches "use" — a view-only grantee sees WHAT is configured, not the resolved, runnable surface. Errors when the id is unknown or the caller cannot see it — visible meaning owned by them, shared with them or one of their teams, or shared org-wide, and ONLY that: toolbox:view/:manage does not widen it, there is no visibility parameter here or on GET /toolbox/:id, and an admin auditing the organization reads nothing they were not given. Call this before toolbox.execute to get the exact tool_name and its argument schema — tool names are provider-specific and must not be guessed — and before toolbox.set_entries, which replaces entries wholesale.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Toolbox id from toolbox.list — a stored id (`tbx_…`), or a dynamic id (`global:usr_…` for everything the caller can run, `connection:conn_…` for one account). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the nested return shape, the presence/absence of `tools` based on access level, the meaning of `delegation` as the bounded summary, and the error conditions for unknown or invisible ids. It does not describe pagination or rate limits, but for a single-resource read with annotations covering safety, this is strong.
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 dense and front-loaded with the core purpose, then the return shape, then access semantics, then usage guidance. Every sentence earns its place, though it is long and somewhat heavy with nested parentheticals. It is structured well enough that an agent can extract the key facts quickly, but the length pushes it just below a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description is remarkably complete. It covers the return shape, the conditional presence of `tools`, the meaning of `delegation`, the error conditions, the visibility rules, and the exact situations in which to call this tool versus siblings. An agent has everything needed to call it correctly and interpret the result.
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 schema already documents the `id` parameter well, including the distinction between stored ids (`tbx_…`) and dynamic ids (`global:usr_…`, `connection:conn_…`). The description adds value by explaining how the id relates to visibility and by warning that tool names are provider-specific and must not be guessed, which is directly relevant to using the parameter correctly. It doesn't add syntax details beyond the schema, but the schema is already rich.
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 opens with a specific verb and resource ('Resolve one toolbox') and immediately distinguishes the tool's scope: it returns the toolbox record plus the resolved, runnable surface when access reaches 'use'. It also names sibling tools (toolbox.execute, toolbox.set_entries) and clarifies what this tool is not, so an agent can select it 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?
The description gives explicit when-to-use guidance: call this before toolbox.execute to get the exact tool_name and argument schema, and before toolbox.set_entries because that replaces entries wholesale. It also states the visibility rules and explicitly says there is no visibility parameter, which prevents an agent from trying to widen scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the toolboxes the caller can see or run: their own, plus every one explicitly shared with them, with one of their teams, or with the whole organization — and nothing else. No permission widens it. toolbox:view and toolbox:manage add nothing here: unlike connections/templates/connectors, toolboxes have NO org-wide oversight listing at all, neither here nor GET /toolbox in the REST API (no visibility parameter exists for them), so this cannot answer "how many toolboxes does the organization have" and must not be reported as if it could — a caller who owns none and has been shared none gets an empty list however privileged they are. Always includes the virtual toolbox global:{the caller’s usr_… id} ("All tools"), which holds every tool they can run across every active connection and is the right default for execution; plus one connection:{conn_…} toolbox per active connection; plus every stored tbx_… toolbox. Ids here are therefore usually NOT tbx_… — pass whatever id you read back verbatim to toolbox.get and toolbox.execute. Only the stored tbx_… rows have grants and a lifecycle (toolbox.update/set_entries/share/unshare/delete); the global:/connection: ids are recomputed from scratch on every call and refuse mutation. A connection needing reauthentication contributes no tools; a stored toolbox whose entry has no connection pinned reports it in needs_connection_count. Returns { result: [...], nextCursor, prevCursor } — camelCase here, unlike the REST API’s next_cursor. Unlike the other lists in this catalog limit defaults to 200 rather than 50, so one call is the entire set for almost every organization. It is still a PAGE: a non-null nextCursor means there are more rows, and the only way to reach them is to send it back as cursor until it comes back null. A page whose nextCursor is not null is never a total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page, 1–200. Defaults to 200 — the whole set in one call for almost every organization — rather than the 50 the other lists here default to. Larger values are clamped, not rejected. | |
| cursor | No | Opaque cursor taken verbatim from a previous call’s `nextCursor`. Omit for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description goes well beyond by disclosing that no permission widens the result, that unprivileged callers get an empty list, that global:/connection: toolboxes are recomputed and refuse mutation, that reauthentication removes tools, and that needs_connection_count appears. It also clarifies pagination is a page, not a total, and that a non-null nextCursor means more rows.
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 long but densely informative and logically organized; the core purpose and scope are front-loaded, followed by permissions, id semantics, lifecycle, and pagination. Some redundancy (e.g., 'A page whose nextCursor is not null is never a total' restates prior pagination text) makes it slightly less concise, but no sentence is 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?
For a complex list tool with no output schema, the description is remarkably complete: it specifies the return shape (result, nextCursor, prevCursor), camelCase vs REST, pagination mechanics, default page size, included toolbox types, id semantics, mutation refusal, reauthentication effects, and the needs_connection_count field. An agent has enough to call it correctly and interpret results.
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 limit's default, min/max, and clamping, as well as cursor being opaque and passed from nextCursor. The description adds comparative context—limit defaults to 200 'rather than the 50 the other lists here default to'—and reinforces cursor usage in a pagination loop, which helps an agent choose values appropriately.
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 opens with a specific verb and precise scope: 'List the toolboxes the caller can see or run: their own, plus every one explicitly shared with them, with one of their teams, or with the whole organization — and nothing else.' It explicitly distinguishes itself from other list tools by stating there is no org-wide oversight listing and that it cannot answer organizational counts, and it names related tools (toolbox.get, toolbox.execute) making the resource boundary clear.
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 explicit when-to-use and when-not-to-use guidance: it can list a caller's visible toolboxes but 'must not be reported as if it could' answer org-wide counts. It also directs the agent to pass returned ids verbatim to toolbox.get and toolbox.execute, identifies which toolboxes are mutable via the toolbox.* lifecycle tools, and explains pagination via cursor, which is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a toolbox’s entries: a WHOLESALE REPLACE, never a merge (name and description are untouched — those belong to toolbox.update). The array you send becomes the toolbox’s entire entry list, so "add the Slack tool" means reading toolbox.get, resending its existing entries and appending yours; sending only the new entry deletes everything else. Each proxy entry needs connector_slug + tool_name; pin connection_id for multi-connection toolboxes, which must be one the ACTING caller can use — they become its delegator (docs/access-model.md §6). An incoming entry whose (connection_id, tool_name) pair matches a PRE-EXISTING one keeps that row’s original delegator rather than re-stamping the caller, so merely re-ordering entries never silently reassigns whose authority a pin rides on. frozen_params and enabled are optional. Validate names against connection.list_tools first — the set is validated as a whole, so one bad entry rejects the call and nothing changes. Only a STORED id may be updated — dynamic ids from toolbox.list are refused. Returns the updated { toolbox, entries } detail.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stored toolbox id (`tbx_…`) from toolbox.list. | |
| entries | Yes | The COMPLETE entry list. Whatever you send replaces every existing entry; entries you omit are deleted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are mostly false and provide little safety context, so the description carries the behavioral burden. It explicitly discloses that omitted entries are deleted, that the replacement is atomic ('one bad entry rejects the call and nothing changes'), and that pre-existing entry delegators are preserved rather than re-stamped.
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 long and dense, but it is front-loaded with the most important fact ('WHOLESALE REPLACE, never a merge') and each sentence adds essential operational detail. It could be broken into clearer paragraphs, but there is no wasteful 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?
For a high-complexity mutation tool with no output schema, this description is remarkably complete. It covers the replace semantics, the read-then-resend workflow, validation behavior, delegator authority, edge cases like re-ordering entries, and even states the return value as '{ toolbox, entries } detail'.
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%, but the description adds meaning beyond the schema: it states that entries is the COMPLETE list, that connector_slug + tool_name are required for proxy entries, and that connection_id determines delegator authority. It also explains that frozen_params and enabled are optional and that id must be a stored id.
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 opens with a specific verb and resource: 'Replace a toolbox’s entries' and immediately distinguishes itself from a merge and from toolbox.update. It clearly separates this tool from siblings like toolbox.update and template.set_entries, so an agent knows exactly what resource and operation this is.
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 explicit when-to-use guidance: it tells the agent to read toolbox.get and resend existing entries before appending, warns that sending only the new entry deletes everything else, and says to validate names against connection.list_tools. It also notes that only stored ids are accepted and dynamic ids from toolbox.list are refused.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a toolbox’s name or description (not entries — use toolbox.set_entries). MERGE: fields you omit keep their current values. description takes a string, or null to clear it; any other type is rejected rather than silently wiping the field. Only a STORED id may be updated — the global:…/connection:… dynamic ids from toolbox.list are recomputed from scratch on every call and are refused here. Returns the updated { toolbox, entries } detail — the same NESTED shape toolbox.get returns, so the name is result.toolbox.name, never result.name.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stored toolbox id (`tbx_…`) from toolbox.list. | |
| name | No | New name. Omit to leave unchanged. | |
| description | No | New description; null clears it. Omit to leave unchanged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false and sparse, so the description carries the full burden. It discloses MERGE semantics, null-clears-description behavior, type rejection of non-string values, refusal of dynamic ids, and the nested return shape. No contradiction with 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?
Dense but every sentence earns its place: scope, merge behavior, null handling, id constraint, and return shape are all packed into a few sentences. The core purpose is front-loaded and the rest are targeted clarifications.
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 explains the return shape explicitly with 'result.toolbox.name, never result.name'. Combined with merge semantics and id restrictions, the description is complete for an agent to call this tool 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% so baseline is 3, but the description adds meaning well beyond the schema: omitted fields keep current values, null clears description, any other type is rejected, and the id must be a stored id rather than the dynamic ids from toolbox.list. These behavioral details are essential for correct invocation.
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: 'Update a toolbox's name or description' and explicitly scopes out entries with 'not entries — use toolbox.set_entries', distinguishing it from sibling tools. The purpose is immediately clear and unambiguous.
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 explicit when-not and alternatives: 'not entries — use toolbox.set_entries' and clarifies that only a STORED id may be updated, refusing dynamic ids from toolbox.list. This tells the agent exactly when to use this tool versus alternatives and what inputs are valid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one tool in one of the user’s connected third-party apps, by its exact name from search_tools. This makes a live call to that app under the user’s own credential, so it can create, change, send or delete real things there, and the app decides whether that can be undone. Confirm the target and the arguments with the user before calling it for anything other than a read. arguments must satisfy the schema search_tools returned for that exact name. If that schema has a connection property, the user has several accounts of that app connected: set it to one of its enum values, copied exactly, and ask the user which account they mean whenever their request does not say.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact tool name as returned by search_tools. | |
| arguments | No | Arguments matching that tool’s own input schema. Send {} if it takes none. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It states that this makes a live call under the user's credential, can create/change/send/delete real things, and that the app decides undoability. It also adds a mandatory confirmation step, making the side-effect and risk profile highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, front-loaded with the core action, followed by risk, user-confirmation guidance, and parameter-handling details. Every sentence earns its place; there is no repetition, fluff, or buried critical context.
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 target selection, live-call risk, confirmation requirements, argument validation, and multi-account disambiguation. It does not explicitly describe the expected return or result shape, which is a minor gap given the absence of an output schema, though the dynamic nature of the underlying tool makes that less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful semantics beyond the schema: arguments must match the schema returned by search_tools, empty arguments are sent as {}, and the connection property requires copying its enum values exactly and asking the user which account is meant. These details are material for correct invocation and are not present in the input 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 names a specific verb and resource: 'Run one tool in one of the user’s connected third-party apps,' and ties the tool name to search_tools. This clearly differentiates it from sibling execute variants like synthetic_tool and toolbox, which are internal constructs rather than third-party app 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 gives explicit directional guidance: use the exact name from search_tools, confirm target and arguments with the user for anything other than a read, and handle multi-account connection properties by asking the user. It does not explicitly name negative-use cases or non-alternatives, but the flow is concrete and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a tool among the user’s connected third-party apps. This is the ONLY way to reach them: they are never listed in tools/list, however few of them there are, so a name you cannot see here is a name you do not have. This connection reaches: Airtable (Pranasri), Google (Pranasri). It indexes THOSE tools and nothing else: it never returns an elaichi__ operation — those administer Elaichi itself and stay listed individually, so an empty result here says nothing about them — and a synthetic (multi-step) tool is here only when it is an entry of a toolbox you can reach; a standalone one is listed by elaichi__synthetic_tool__list and run by elaichi__synthetic_tool__execute. Searching runs entirely inside Elaichi and touches no third party, so it is cheap and safe to call. Returns each match with its exact name, description and input schema. Ranking is lexical over the name, the app and the description, so query with concrete tool-ish words like "create deal" rather than a sentence. Omit the query to browse the first tools instead. Results are paged: a result that reports more matches than it returned carries a next_cursor, and passing it back as cursor gets the next page — so a tool you did not see on page one has not been ruled out. Then call execute_tool with a name exactly as returned, never one you have reformatted or guessed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 10, maximum 50). | |
| query | No | A few concrete words for the action you want, e.g. "create deal". Omit it to list the first tools instead of searching. | |
| cursor | No | Continue a previous search. Pass back the `next_cursor` a previous search_tools result gave you, with the same query, to get the following page. Omit it for the first page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, the description adds meaningful behavioral detail: searching "runs entirely inside Elaichi and touches no third party," making it safe and cheap. It also discloses lexical ranking, pagination via next_cursor, and the implication that an empty page does not rule out further tools. This goes well beyond the structured 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 longer than typical, but nearly every sentence adds distinct value: scope, exclusions, safety, ranking, paging, and the next step. A little redundancy exists with the schema (e.g., "Omit the query to browse the first tools"), but the structure is front-loaded with the core purpose and the boundaries are clearly highlighted. It earns a high score without being fully crisp.
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 that there is no output schema, the description compensates well by stating that each match includes exact name, description, and input schema, and by explaining pagination and how to continue. It also covers the tool's scope boundaries and the follow-up execute_tool call. For a read-only search tool with these annotations and sibling context, nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% parameter description coverage, so the baseline is 3. The description adds genuinely useful semantics beyond the schema: it explains how to phrase the query (concrete tool-ish words rather than sentences), clarifies that omitting the query browses the first results, and describes cursor behavior with the same query for continued paging. Minor credit is withheld because the description does not elaborate on the limit parameter, but overall it improves parameter understanding.
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: "Find a tool among the user's connected third-party apps." It clearly differentiates this tool from siblings by emphasizing it is the "ONLY way" to reach those apps, that they are never in tools/list, and that it never returns elaichi__ operations or standalone synthetic tools. This leaves no ambiguity about what the tool is for or how it differs from nearby alternatives.
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 explicit when-to-use and when-not-to-use guidance. It says connected third-party tools are only reachable here, explicitly excludes elaichi__ operations, routes standalone synthetic tools to elaichi__synthetic_tool__list/execute, and instructs the caller to follow up with execute_tool using the exact returned name. This is model-level usage guidance, far beyond a generic statement.
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.
elaichi__access_request__createelaichi__access_request__getelaichi__access_request__listelaichi__access_request__resolveelaichi__access_request__withdrawelaichi__connection__createelaichi__connection__getelaichi__connection__listelaichi__connection__list_toolselaichi__connection__reconnectelaichi__connection__renameelaichi__connection__shareelaichi__connector__getelaichi__connector__listelaichi__connector__list_toolselaichi__feedback__createelaichi__invite__createelaichi__invite__listelaichi__member__getelaichi__member__listelaichi__member__offboardingelaichi__member__set_roleselaichi__organization__getelaichi__permission__listelaichi__role__getelaichi__role__listelaichi__synthetic_tool__createelaichi__synthetic_tool__executeelaichi__synthetic_tool__getelaichi__synthetic_tool__listelaichi__synthetic_tool__updateelaichi__team__add_memberelaichi__team__createelaichi__team__getelaichi__team__listelaichi__team__set_member_adminelaichi__team__updateelaichi__template__createelaichi__template__getelaichi__template__listelaichi__template__set_entrieselaichi__template__shareelaichi__template__updateelaichi__toolbox__createelaichi__toolbox__executeelaichi__toolbox__getelaichi__toolbox__listelaichi__toolbox__set_entrieselaichi__toolbox__shareelaichi__toolbox__updateexecute_toolsearch_tools
Add one secure layer between your agents and this server.