past.dev is a long-term memory API for AI agents. Send it timestamped text such as emails, meeting transcripts and support tickets. Ask a question and get the current fact, the value it replaced and the source behind it. With this server, your assistant can recall and save memory and manage your past.dev account.
Scored across 67 tools
Many tools share overlapping domains: organization retrieval (get_organization vs admin_get_organization), credit operations (admin_grant_credits, admin_invoice_credits, admin_quote_credits), access granting (grant_project_access, create_access_rule, create_access_group), and trace views (get_lineage, get_timeline, find_trace_roots). The detailed descriptions clarify these differences, but the sheer number of similar-sounding operations increases the risk of misselection.
Nearly all tools follow a consistent snake_case verb_noun pattern (e.g., list_projects, create_issue, admin_get_organization). The only clear deviation is request_histogram, which uses a noun_noun form, and the admin_ prefix is used consistently as a namespace for internal staff tools.
With 67 tools, the surface is far above the typical 3-15 range and exceeds the 25-tool threshold for being heavy. While each tool maps to a distinct operation in a complex platform, the count is excessive for an MCP server and likely to overwhelm agents.
The set covers CRUD for projects, access groups, rules, tags, API keys, members, and comprehensive ingestion, recall, trace, usage, and admin contract/signup operations. Minor gaps remain, such as no tool to configure the MCP login connection or list audiences explicitly, but core workflows are well supported.
Internal staff only. Creates a sign-up campaign: every new organization opened through its link is granted the credits, once, under the reason the customer's Billing screen shows. Granted credits never lapse and cannot be taken back. Answers the link to hand out. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| endsAt | No | When the link stops granting: an ISO 8601 date (the start of that day, UTC) or date-time in the future. Omitted, the campaign runs until it is ended. | |
| reason | Yes | The reason each grant carries, in at most 500 characters. The customer reads it beside the grant. | |
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| credits | Yes | The credits each new organization is granted, between 1 and 50,000,000. | |
| campaign | Yes | The campaign's code, its link's utm_campaign: a letter or digit, then up to 99 letters, digits, dots, underscores or hyphens. Stored in lower case. | |
| maxOrganizations | No | How many organizations it grants at most, between 1 and 1,000,000. Omitted, uncapped. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=false, and the description richly reinforces and extends this: credits 'never lapse and cannot be taken back', spelling out irreversibility. It also discloses the two-phase confirm handshake and its return of the link and a confirmation sentence, which the annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the audience and purpose, which is good, but several sentences are convoluted ('Answers the link to hand out', 'put the sentence it answers with to the person'), making the intended behavior harder to parse than necessary for the word count.
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 6-parameter, destructive, no-output-schema tool, the definition covers the key things an agent needs: audience restriction, irreversible credit grant, the confirm workflow, and what the unconfirmed call returns. Minor gaps remain around error/precondition handling and the precise returned link.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for confirm ('call it without confirm first') and for reason ('the reason the customer's Billing screen shows'), tying parameters to the workflow rather than merely restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Creates a sign-up campaign') and immediately explains the effect: every new organization opened through its link gets credits once. However, it never explicitly differentiates itself from siblings like admin_update_signup_campaign or admin_end_signup_campaign beyond the word 'Creates', so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear procedural context: it is 'Internal staff only', and prescribes a two-step flow ('Call it without confirm first... and call again with confirm: true only when they agree'). This tells the agent exactly when to set confirm. It falls short of naming an alternative tool (e.g. update/end campaign) for edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Ends a sign-up campaign now: its link grants nothing from this moment, and the organizations it granted keep their grants. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| campaign | Yes | The campaign's code, as admin_list_signup_campaigns lists it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, idempotentHint=true and a closed world, so the burden is lower, yet the description adds what annotations cannot: the termination is forward-looking only and does not claw back organizations already granted, and the call is deliberately gated behind a human confirmation round-trip. That is exactly the kind of consequence detail an agent needs before a destructive action.
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 tight sentences, front-loaded with the access restriction and the state effect before the invocation protocol. No filler; every clause carries either a constraint, a consequence, or an instruction.
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 destructive tool with no output schema, the description covers audience, irreversible consequence, preserved state, and the confirmation loop, and even hints that the unconfirmed call returns a sentence to relay. Nothing material is left for the agent to guess.
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 both parameters are already documented, and the description largely restates the schema's confirm semantics and the campaign-code reference rather than adding format or edge-case detail. Baseline 3 applies when the schema carries 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?
States a specific verb (Ends) on a specific resource (a sign-up campaign) and then defines the exact effect: the link grants nothing from this moment while already-issued grants persist. That effect statement cleanly separates it from siblings like admin_update_signup_campaign or admin_create_signup_campaign.
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?
Restricts the audience (internal staff only) and prescribes a precise two-phase protocol: call without confirm first, relay the returned sentence to the person, and only re-call with confirm: true once they agree. An agent knows both the precondition and the exact sequencing required before invoking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Finds organizations anywhere on this deployment from what you were told about a customer: the organization's id or slug, a member's exact address, the domain members sign in from ("@acme.com" or "acme.com"), or part of the name. At most ten, the most exact matches first, each with its id, slug, status, plan, member count and what matched. An organization a coding agent made names that agent (createdByAgent); while nobody has claimed it, it reads unclaimed, with the date it is deleted unless claimed (unclaimedUntil), and its name and its one member are placeholders. Pass the id to admin_get_organization or admin_grant_credits.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | An organization id or slug, a member's address, a domain, or part of the organization's name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, non-open-world, so the safety bar is low; the description goes well beyond by disclosing the result cap ('At most ten'), the ranking rule ('most exact matches first'), the returned fields, and the special unclaimed-organization semantics (createdByAgent, unclaimedUntil, placeholder name/member). That is substantive behavioral context an agent could not infer from 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?
Front-loads the audience and the core lookup modes, then layers ranking and edge-case semantics. It is dense and the unclaimed-organization sentence is long, but every sentence carries actionable information rather than 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, single-parameter search with no output schema, the description supplies the result count limit, ordering, returned fields, and the unclaimed-org caveat, and names the follow-up tools. 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 single 'query' param is fully documented in the schema, so the baseline is 3. The description mostly restates the accepted input types but does add the concrete domain format examples ('@acme.com' or 'acme.com'), a marginal gain over 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 and resource ('Finds organizations anywhere on this deployment') and immediately frames the lookup modes (id, slug, member address, domain, partial name). It implicitly distinguishes itself from admin_get_organization by telling the agent to pass the id there once found, so the find-vs-fetch split is legible without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Internal staff only' sets the audience, and 'from what you were told about a customer' frames the triggering situation clearly. The closing 'Pass the id to admin_get_organization or admin_grant_credits' routes the agent to the next step, though it never states explicitly when NOT to use this versus get_organization.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. An organization's filed Enterprise contract, named by its id or slug: the term, the commitment and its rate, the terms that set its Enterprise plan (credits a month, how long bought credits last, days to pay an invoice, the monthly fee) and who filed it, beside the plan those terms make right now and the billing email Stripe sends its invoices and receipts to. contract is null where none is filed.
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that with the null-absence semantics ('contract is null where none is filed') and the internal-staff access restriction, both of which are real 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 permission note is front-loaded, but the body is one sprawling sentence that crams an entire field inventory into a single breath. The detail is dense rather than redundant, yet the enumeration would read better structured or left to a return-value schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description carries the burden of explaining returns, and it does so thoroughly: field inventory, the live-plan pairing, billing email, and the null-when-unfiled case. It is essentially complete for a single-parameter read 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% and the single parameter is fully documented as 'the organization's id or slug, as admin_find_organization returned it.' The description's 'named by its id or slug' merely restates the schema, adding no format or syntax detail beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource (an organization's filed Enterprise contract) and enumerates its contents — term, commitment, rate, plan-setting terms, filer, current plan, billing email — so the agent knows exactly what it retrieves. It indirectly distinguishes itself from siblings like admin_get_organization and admin_set_contract, though the verb is only implied by the title rather than stated.
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?
'Internal staff only' establishes an audience restriction, which is genuinely useful access guidance. However, it offers no when-to-use versus alternatives (e.g., admin_get_organization, get_plan) and no preconditions beyond the audience note, leaving selection logic implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. One organization on this deployment, named by its id or slug: its status and creation date, its plan and subscription, its Stripe customer and subscription ids (to compare with Stripe's dashboard), the credits it was granted at sign-up, its members and pending invitations, and the credits granted to it (the latest twenty, each naming the sign-up campaign behind a campaign grant, and everything ever). An organization a coding agent made names that agent (createdByAgent); while nobody has claimed it, it reads unclaimed, with the date it is deleted unless claimed (unclaimedUntil), and its one member is a placeholder nobody signs in as. It does not read the balance, which lives in the organization's own database; the customer's Billing screen shows it.
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description then goes well beyond by enumerating the returned fields (status, creation date, plan/subscription, Stripe ids, sign-up credits, members, invitations, granted credits) and disclosing special read states (createdByAgent, unclaimed, unclaimedUntil, placeholder member). It even states a negative boundary — it does not read the balance, which lives in the org's own database — and points to where that value is shown.
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?
Content is dense and nearly all substantive, with the key constraint ('Internal staff only') front-loaded. However it is delivered as one sprawling multi-clause sentence, which makes it harder to parse than a structured enumeration would be; structure is the weak point rather than length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must carry the return-value burden and it does so thoroughly, describing the fields, the special unclaimed/agent-created states, and what it deliberately omits. Nothing an agent needs to call this correctly appears 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% for the single required param, so the schema already documents 'The organization's id or slug'. The description confirms the same meaning ('named by its id or slug') without adding format rules or edge cases beyond what the schema provides; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (show/get) and resource (one organization) and pins the scope to a single org addressed by id or slug. The distinction from admin_find_organization is implicit through the param note ('as admin_find_organization returned it'), and the sibling public get_organization is conceptually separate since this one is admin-scoped. An agent can tell what it retrieves without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Internal staff only' is an explicit audience/prerequisite gate, and the parameter explicitly routes the agent through admin_find_organization first to obtain the id or slug. There is no explicit statement of when to prefer this over the non-admin get_organization or other org-related siblings, so it falls short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Grants an organization credits: they are spent after its included credits, never lapse, and cannot be taken back; the grant is recorded with your address as its author and the reason as the customer's Billing screen shows it. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree. Calling twice with confirm grants twice.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | Why, in at most 500 characters. The customer sees it beside the grant. | |
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| credits | Yes | How many credits, between 1 and 50,000,000. | |
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say destructive/non-idempotent; the description goes well beyond them by disclosing that credits never lapse, cannot be taken back, are attributed to the caller's address, and appear on the customer's Billing screen. It also explicitly warns that calling twice with confirm grants twice, which explains the practical consequence of the non-idempotent hint.
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?
Five tight sentences, front-loaded with the audience restriction and the consequences of the action before the procedural instructions. Every clause carries information an agent needs to act correctly.
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, and the description compensates by stating that the unconfirmed call returns a sentence meant for the customer. Combined with the irreversibility and attribution notes, an agent has everything needed to execute this destructive, non-idempotent two-step operation safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: it explains the two-call confirm protocol that the 'confirm' boolean participates in and why 'reason' exists (the customer sees it). It does not add anything for 'organization' or 'credits' 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?
States a specific verb and resource ('Grants an organization credits') and immediately distinguishes itself from the adjacent admin_invoice_credits / admin_quote_credits siblings by defining how granted credits behave (spent after included credits, never lapse, irreversible). Also flags its audience ('Internal staff only'), which further separates it from ordinary credit 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?
Gives an explicit operational protocol: call without confirm first, relay the returned sentence to the customer, call again with confirm:true only after they agree. That is unusually clear when-to-use guidance for a two-phase mutation. It does not name a sibling alternative (e.g. invoice vs. grant credits), which is the only missing piece for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Sends an organization a Stripe invoice for credits at its Enterprise contract's prices, due in the contract's days to pay; the credits are added once it is paid and last the contract's months from then. A price in place of the contract's needs approvedBy: who approved it, in writing, and when. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree. Calling twice with confirm sends two invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| credits | Yes | How many credits, a whole number of thousands. | |
| approvedBy | No | Who approved that price, in writing, and when. Required with it. | |
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. | |
| approvedPricePerThousand | No | A price per 1,000 credits, in the currency's units, approved in place of the steps. Leave out to price on the steps. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this destructive and non-idempotent, but the description adds real substance: a two-step confirm handshake with a human, the consequence of double-confirming, the fact credits only land after payment, and that a non-contract price requires written approval recorded in approvedBy. It does not describe auth mechanics or failure modes beyond the approval requirement.
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?
Five tightly packed sentences, front-loaded with the access restriction and the core action, with zero filler. Some phrasing is convoluted ('put the sentence it answers with to the person'), which slightly reduces scannability but does not waste space.
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 usefully explains that the unconfirmed call returns 'a sentence' to relay — information the agent would otherwise lack — and covers authorization, side effects, and the approval prerequisite. It stops short of describing what a confirmed call returns or handles any error/retry case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented, making 3 the baseline. The description does clarify the conditional dependency between approvedPricePerThousand and approvedBy ('A price in place of the contract's needs approvedBy'), which the schema only gestures at with 'Required with it', but it adds no syntax or format detail beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'Sends an organization a Stripe invoice for credits at its Enterprise contract's prices' — and explains the downstream effect (credits added once paid, lasting the contract's months). It implicitly separates this from grant/quote siblings by describing an invoice-based mechanism, but never names admin_grant_credits or admin_quote_credits, so an agent still has to infer which of the three credit tools applies.
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?
Excellent operational guidance: 'Internal staff only', call without confirm first, relay the sentence to the person, and only re-call with confirm: true once they agree, plus the warning that two confirmed calls send two invoices. There is no explicit when-not guidance against the sibling tools (quote_credits, grant_credits), which is the main remaining ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Every sign-up campaign, newest first, each with its credits, reason, end, cap, the organizations granted so far, its status (active, ended or full), its author and its link. Given a campaign's code, that campaign alone, the organizations still holding its grant and the credits they were granted in all, and the latest 50 of them. An organization deleted since is in the campaign's count and nowhere else.
| Name | Required | Description | Default |
|---|---|---|---|
| campaign | No | One campaign's code. Omitted, every campaign. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds value beyond them: the staff-only access requirement, the newest-first ordering, an explicit pagination limit ('the latest 50 of them'), and a genuine edge-case disclosure — a deleted organization is still counted in the campaign but appears nowhere else. That last item is information an agent could not derive from annotations or 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 content is dense and mostly earns its place, but the second sentence is a long elliptical fragment ('Given a campaign's code, that campaign alone, the organizations still holding its grant...') that is hard to parse on first read. Leading with the staff-only constraint before the purpose also delays the front-loaded 'what it does'. Adequately sized, but the syntax costs 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?
With no output schema, the description carries the return-value burden and largely discharges it: it lists the fields shared across campaigns, describes the per-campaign detail mode, and notes the 50-item limit. Combined with annotations (safety profile) and a fully documented single parameter, an agent has enough to call it correctly; only the exact response shape for the aggregate credit figures stays vague.
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 states 'One campaign's code. Omitted, every campaign,' so the baseline would be 3. The description goes further by describing what the output becomes when the parameter is set (that campaign alone, its still-held grants, aggregate credits, latest 50), giving the parameter mode-dependent meaning beyond the schema 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?
The tool is clearly a read of sign-up campaigns — all of them newest-first, or one when a code is supplied — and it enumerates the returned fields (credits, reason, end, cap, organizations, status, author, link). The reference resource is unambiguous. It never names or contrasts the sibling mutation tools (admin_create_signup_campaign, admin_end_signup_campaign), so the differentiation is only implied by the 'list' framing.
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?
'Internal staff only' gives a real pre-condition, and the description does explain the two selection modes (omit the code vs. supply one). Beyond that there is no when-to-use/when-not guidance and no pointer to alternative tools for campaign inspection or creation. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. What a purchase of credits costs on an organization's Enterprise contract: priced on the contract's steps from the credits invoiced since its term began, one line per price, or at a price somebody approved in place of them. Sends nothing; admin_invoice_credits sends the invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| credits | Yes | How many credits, a whole number of thousands. | |
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. | |
| approvedPricePerThousand | No | A price per 1,000 credits, in the currency's units, that somebody approved in place of the steps. Leave out to price on the steps. |
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 structurally. The description adds genuine value beyond that: it confirms no side effect occurs ('Sends nothing') and discloses an auth/audience constraint ('Internal staff only'), which annotations do not express.
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 audience constraint is correctly front-loaded in the first clause, and the whole thing is two dense sentences with no filler. The middle sentence is somewhat run-on, but every clause carries information 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?
For a read-only tool with no output schema, the description does the needed work: it conveys the return shape ('one line per price') and rules out side effects, which is what an agent must know before calling it. Nothing critical is missing, though a hint about error/eligibility behavior on non-Enterprise contracts is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantics behind the pricing modes – pricing 'on the contract's steps from the credits invoiced since its term began' versus 'at a price somebody approved in place of them' – which gives the agent conceptual grounding for approvedPricePerThousand rather than just repeating its schema 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?
States a specific verb and resource ('What a purchase of credits costs on an organization's Enterprise contract') and immediately distinguishes itself from the sibling that actually performs the write, admin_invoice_credits. An agent can tell this is a pricing/quote operation versus an invoicing operation without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly scopes the audience ('Internal staff only') and names the alternative plus the condition that selects it: this tool 'sends nothing' while 'admin_invoice_credits sends the invoice.' The pricing-mode choice (steps vs. approved price) is also stated as an explicit either/or.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Files an organization's Enterprise contract, replacing the one filed before: every term is set again, and a term left out returns to the Enterprise catalog's figure. On Enterprise the terms set the plan from the moment they are filed: the credits each period includes, how long bought credits last from payment, and, with payment days, that an overdue invoice withholds the month's credits until it is paid. The signed PDF is kept; filing a new one is the contract command line's. Money is in minor units of the currency (USD 500.00 is 50000). billingEmail is required: the address Stripe sends the contract's invoices and receipts to, which becomes the organization's billing email. Ask the person for it when they have not given it, and never guess it from a name. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| termEnd | Yes | The day the term ends and the contract renews, yyyy-mm-dd. | |
| currency | Yes | The three-letter currency, such as USD. | |
| termStart | Yes | The first day of the term, yyyy-mm-dd. | |
| invoicesTo | No | Who the contract says invoices go to, as a name, if it says. Where they are sent is billingEmail. | |
| monthlyFee | No | The fee invoiced each month, in minor units. Leave out where there is none. | |
| creditTiers | No | The prices the contract sells credits at, graduated over the term: each step's start in credits bought this term (the first starts at 0) and its price per 1,000 credits in the currency's units, such as [{fromCredits: 0, pricePerThousand: 0.05}, {fromCredits: 50000000, pricePerThousand: 0.075}]. Leave out and the contract sells no credits. | |
| paymentDays | No | Days the customer has to pay an invoice Stripe sends. Leave out for a contract paid by card. | |
| billingEmail | Yes | The email address Stripe sends this contract's invoices and receipts to; it becomes the organization's billing email. Ask the person for it if they have not given it. Never guess it from a name. | |
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. | |
| purchaseOrder | No | The purchase order number, if the contract has one. | |
| committedAmount | Yes | What a year's commitment costs, in minor units of the currency. | |
| includedCredits | No | Credits each billing period includes, in place of the catalog's 5,000,000. Leave out to keep the catalog's. | |
| ratePerThousand | Yes | The price of 1,000 credits past the commitment, in minor units. | |
| committedCredits | Yes | Credits committed for each contract year. | |
| purchaseCapCredits | No | The most credits bought over the term at these prices. Leave out for no cap. | |
| purchaseMinimumCredits | No | The fewest credits one purchase buys, a whole number of thousands. Leave out for 1,000. | |
| boughtCreditsValidityMonths | No | Months a bought credit lasts from the day its invoice was paid. Leave out and bought credits never lapse. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description earns its keep by spelling out exactly what destruction means: prior terms are wiped, omitted terms silently revert to catalog defaults, and an overdue invoice withholds the month's credits. It also flags the confirmation gate and the 'never guess billingEmail' failure mode — context well beyond the annotation set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads audience restriction and the operation's identity, then layers destructive semantics, unit conventions, and finally the confirm protocol. Dense but every clause carries distinct information for an 18-parameter destructive tool; nothing is restated from the schema wholesale.
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 destructive mutation with 9 required parameters and no output schema, it covers the essentials: precondition, wipe semantics, currency units, required email, and the confirm handshake. Minor gaps remain around idempotency on re-filing and what the unconfirmed 'sentence' contains, but the agent has enough to call it safely.
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% across all 18 parameters, so the baseline is 3. The description adds cross-cutting semantics the schema states only per-field — that all money is in minor units (USD 500.00 = 50000), that billingEmail is mandatory and must come from the person, and how confirm interacts with the rest.
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 ('Files an organization's Enterprise contract') and immediately distinguishes itself from the read sibling by explaining it 'replac[es] the one filed before.' The reset semantics ('every term is set again, and a term left out returns to the Enterprise catalog's figure') make the operation distinguishable from admin_get_contract without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a hard precondition ('Internal staff only') and an explicit two-step procedure: call without confirm, relay the sentence to the person, then call with confirm: true only on agreement. It does not explicitly route the agent between this tool and the other contract-adjacent siblings (admin_get_contract, admin_quote_credits), which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Puts an organization on Pay as you go onto Flex free for some months, for a startup program or any other deal: creates its Stripe customer where it holds none, starts a Flex subscription at 100% off for those months that cancels itself when they end, and records the plan at once. Nothing is ever charged; when the months end the organization returns to Pay as you go. An organization already on Flex or Enterprise is refused. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| months | Yes | How many months Flex is free, from 1 to 12. The subscription ends after them. | |
| reason | Yes | Why, in at most 500 characters, for example "Startup program". Stored on the Stripe subscription. | |
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| program | Yes | The program the organization joins, as a slug: startup-program for the startup program. It names the hidden coupon and is stored on the Stripe subscription as past_program, which is how the program's accounts are listed and counted. | |
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (destructiveHint=true, idempotentHint=false): nothing is ever charged, the subscription cancels itself at the end of the term, the organization reverts to Pay-as-you-go, and the confirm-gated two-phase invocation is spelled out. Refusal conditions are also disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the audience restriction and the action, and every sentence conveys a real constraint (refusal case, billing behavior, confirm protocol). It is dense and paragraph-heavy, but not 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?
No output schema exists, yet the description explains what the unconfirmed call returns (a sentence to relay) and the state the organization ends in. For a destructive, non-idempotent admin mutation, an agent has everything needed to invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents months, reason, program, confirm, and organization. The description reinforces the confirm workflow and the program slug's role, but adds little parameter meaning the schema does not already carry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource with full mechanism: puts an organization from Pay-as-you-go onto Flex free for N months, creating the Stripe customer, starting a self-cancelling 100%-off subscription, and recording the plan. This is clearly distinguishable from siblings like admin_grant_credits or admin_set_contract.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a strong precondition (internal staff only; an organization already on Flex or Enterprise is refused) and an explicit two-step call protocol: call without confirm, relay the returned sentence to the person, then re-call with confirm: true once they agree. It does not name an alternative sibling for other deal types, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Brings an organization's plan to what Stripe bills it for: lists the subscriptions of the Stripe customer the organization holds and writes each one's row exactly as a Stripe subscription event would. Use it when an organization paid for Enterprise (or Flex) in Stripe but still reads Pay as you go. A subscription on a price that maps to no plan writes nothing, and the answer names it. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| organization | Yes | The organization's id or slug, as admin_find_organization returned it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: it is internal-staff-only, the write overwrites plan rows to mirror Stripe, a price mapping to no plan writes nothing, and the call is designed as a two-step dry-run-then-confirm flow. It does not detail rollback or permission requirements beyond the staff note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the critical constraint ('Internal staff only') and then the mechanism, trigger, edge case, and procedure in order. Roughly four sentences with little waste, though the confirm workflow partly duplicates the schema's confirm description.
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 destructive, confirm-gated mutation with no output schema, the description covers trigger, mechanism, no-op behavior, staff restriction, and the required two-call interaction. What the call returns is described qualitatively ('the answer names it'), so nothing essential to correct invocation is missing, though outcome details remain thin.
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 both parameters are documented, including confirm's meaning, which the description largely restates. The description adds the procedural nuance that the unconfirmed call returns a sentence to present to the person, which enriches confirm's semantics slightly, but organization gets no added meaning. Baseline 3 with mild uplift.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: it states exactly what it does to an organization's plan ('Brings an organization's plan to what Stripe bills it for') and even describes the mechanism (lists the Stripe customer's subscriptions and writes each row as a subscription event would). This is clearly distinguishable from admin_get_organization and admin_get_contract, which read rather than reconcile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger condition ('Use it when an organization paid for Enterprise (or Flex) in Stripe but still reads Pay as you go') and a precise operating procedure (call without confirm first, show the sentence, then confirm). No sibling alternatives are named, and the no-op case is stated as a condition rather than a when-not-to-use rule, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Internal staff only. Changes a sign-up campaign's terms for the sign-ups from now on; the organizations it has granted keep what they received. A term left out keeps its value, so an end or a cap can be moved, never removed. A future endsAt runs an ended campaign again. Call it without confirm first, put the sentence it answers with to the person, and call again with confirm: true only when they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| endsAt | No | The new end: an ISO 8601 date (the start of that day, UTC) or date-time in the future. | |
| reason | No | The reason each new grant carries, in at most 500 characters. | |
| confirm | Yes | true only once the person has agreed to the sentence the unconfirmed call answered with. | |
| credits | No | The credits each new organization is granted, between 1 and 50,000,000. | |
| campaign | Yes | The campaign's code, as admin_list_signup_campaigns lists it. | |
| maxOrganizations | No | The new cap, between the organizations already granted and 1,000,000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond annotations: changes are non-retroactive ('organizations it has granted keep what they received'), patch semantics ('a term left out keeps its value... never removed'), and the edge case that a future endsAt reactivates an ended campaign. This complements destructiveHint/idempotentHint with concrete consequences the annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the access restriction and the core operation, then sequences the confirm protocol. Dense but every sentence carries behavioral weight; the only minor cost is a slightly run-on middle passage.
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 destructive, no-output-schema mutation with six parameters, the description covers non-retroactivity, omitted-term semantics, re-activation behavior, and the two-phase confirm contract. It does not spell out failure/permission details, but nothing essential to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description contributes real semantic value beyond the schema: it explains patch/omission behavior for terms and the meaning of the confirm round-trip. This goes beyond what the individual parameter descriptions state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Changes a sign-up campaign's terms') and clarifies the prospective scope ('for the sign-ups from now on'), which naturally separates it from admin_end_signup_campaign and admin_create_signup_campaign. It stops short of naming any sibling explicitly, so it is clear but not sibling-differentiating by name.
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 strong procedural when/how: 'Internal staff only' plus an explicit two-phase flow (call without confirm, relay the sentence to the person, then call again with confirm: true only on agreement). It does not route between sibling tools, but the usage condition for this tool itself is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archives a project, as Archive on Settings › Projects does: out of the switcher, every call on its keys refused, its data still readable. The organization's last live project cannot be archived. Needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (destructive, idempotent, not read-only), and the description adds real context beyond them: the operational consequence (out of switcher, key calls refused, data preserved) plus a hard precondition and the required permission level.
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 dense sentences, front-loaded with the core behavior, then constraints and auth. No padding, and every clause conveys actionable 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 mutation with no output schema, the description covers consequence, precondition, and permission, which is everything an agent needs to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already explains the 'project' slug and its omission rule, so the description adds nothing about the parameter. Baseline 3 is correct when the schema does the heavy lifting.
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 ('Archives') and resource ('a project') and disambiguates the semantics from deletion by noting 'every call on its keys refused, its data still readable'. An agent can distinguish it from delete_project without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear preconditions ('the organization's last live project cannot be archived', 'Needs project Admin') and implies the archive-vs-delete distinction, but never explicitly names alternatives such as unarchive_project or delete_project or states when to prefer them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a group of members that rules can name. A group grants nothing until a rule names it. Mirrors New group on Settings › Roles & access; needs Owner or Admin. Only members who have joined can be added.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The group's name. | |
| userIds | No | Its members by userId, as list_members returns it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds genuinely useful context the annotations lack: the security model (a group grants nothing until a rule names it), the required role (Owner or Admin), and the membership precondition. It does not discuss return shape or what happens on duplicate names.
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 terse sentences, each carrying distinct information: what it creates, how it relates to rules, and the operational prerequisites. Front-loaded with the core purpose and 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?
With no output schema, the description should carry the return expectations, and it does not say what the call returns (e.g., the new group id). Everything else an agent needs to invoke the tool correctly, permissions, membership constraint, relationship to rules, is present, so the gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already defines both name and userIds, and the description adds no syntax or format detail beyond them. The one behavioral hint, "only members who have joined can be added," constrains userIds but is framed as a requirement rather than a parameter explanation. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ("Creates a group of members") and immediately distinguishes it from the closely related rule concept with "A group grants nothing until a rule names it." An agent can tell this apart from create_access_rule and list_access_groups without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context and prerequisites: "Mirrors New group on Settings › Roles & access; needs Owner or Admin. Only members who have joined can be added." That tells the agent the permission bar and the membership constraint. It stops short of naming when-not-to-use or a sibling alternative, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a tag-matched rule: the groups and people it names reach every live project its tags match, at its level, until it lapses. Mirrors New rule on Settings › Roles & access; needs Owner or Admin. Name at least one group or person, and give tags unless match is Every. Call preview_access_rule first and tell the person what it would reach.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | The tags to match; required unless match is Every. | |
| level | Yes | Read, Write or Admin. | |
| match | Yes | All (the project carries every tag), Any (at least one), or Every (every live project, whatever it carries). | |
| userIds | No | People by userId, as list_members returns it. | |
| groupIds | No | Group ids, as list_access_groups returns them. | |
| expiresAt | No | When the rule lapses, as an ISO 8601 date or time in the future; omitted, it never does. A date already past is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (not read-only, non-destructive, non-idempotent, closed-world). The description adds non-obvious context the annotations cannot: it requires Owner/Admin, the rule persists 'until it lapses', and it affects 'every live project its tags match'. It does not restate idempotency or destructive semantics, but that is covered by 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, front-loaded with what the tool creates before moving to prerequisites and the preview workflow. Dense but largely waste-free; the 'Mirrors New rule on Settings › Roles & access' clause is useful orientation but slightly redundant with the rest.
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 and full schema coverage, the description covers everything an agent needs: effect scope, auth requirement, required-input constraints, expiry behavior, and the mandatory preview step. No meaningful gap remains.
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. The description goes beyond the schema by surfacing a constraint the schema does not encode: though only match and level are marked required, at least one of groupIds/userIds must be supplied, and tags are needed unless match is Every. That is genuine added meaning, not repetition.
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 (Creates) and resource (tag-matched rule) and explains the actual semantics: named groups/people reach every live project matching the tags, at the given level, until expiry. This clearly distinguishes it from create_access_group, update_access_rule, and delete_access_rule, and the UI mirror ('New rule on Settings › Roles & access') anchors it further.
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 prescribes the workflow ('Call preview_access_rule first'), states the auth prerequisite (needs Owner or Admin), and gives the validity conditions (name at least one group or person; supply tags unless match is Every). That is when-to-use, prerequisite, and constraint guidance in one place.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mints a project key named name, attributed to the person under Created by. The answer carries the key's clear value: show it to the person once, and never paste it anywhere but back to them, since it is not recoverable here afterwards. Mirrors API keys › Create key; needs project Admin. Name the project by slug; omit it when the organization has one live project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| project | No | The project's slug; omitted, the organization's only live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (non-readonly, non-idempotent, non-destructive), the description discloses genuinely useful behavioral facts: the returned key's clear value is shown once and is not recoverable afterwards, and the call requires project Admin. That secret-handling and authorization context is exactly what annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and the critical one-time-secret warning, and every sentence carries information. The phrasing ("never paste it anywhere but back to them") is slightly verbose but earns its place as a security constraint.
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 two-parameter create tool with no output schema, the description covers the essential gaps: admin permission, project-slug defaulting, and one-time secret visibility. Minor omissions (key format, per-project key limits) are not significant enough to block 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 50%: the `project` parameter is documented in the schema, while `name` is not. The description only implies that `name` is the key's label and largely repeats the project-slug rule already in the schema, so it adds marginal meaning over the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ("Mints a project key") plus the attribution behavior and a mapping to the API keys › Create key operation. It does not explicitly distinguish itself from siblings like revoke_api_key or list_api_keys, so it lands just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a prerequisite ("needs project Admin") and a conditional parameter rule ("Name the project by slug; omit it when the organization has one live project"). It stops short of naming alternatives or when-not-to-use cases, so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mints an access link to a project's MCP server for one identity: an MCP URL whose secret is the credential, so a client connects with it and every call runs as that identity, with no sign-in. The server must be on. identity names an identity the project already holds; with newIdentity: true it is created here, with traits (for example {"kind": "agent"}), which decide the audiences it is in. The answer carries the link: show it to the person once, and never paste it anywhere but back to them, since it is not recoverable here afterwards. Mirrors Build › MCP server › Create access link; needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| traits | No | Traits for a new identity, as key and value. Only with newIdentity: true. | |
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. | |
| identity | Yes | The identity the link is for, as the project's identity directory names it. | |
| expiresAt | No | When the link stops working, as an ISO 8601 date or time in the future; omitted, it never does. | |
| newIdentity | No | Create the identity with this link. Refused when the project already holds it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only say non-read-only, non-destructive, non-idempotent), it discloses the crucial traits of the artifact: the link embeds a credential and cannot be recovered here afterwards, so it must be shown once and not pasted elsewhere. It also adds the auth requirement (project Admin) and the server-must-be-on precondition, none of which the annotations carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose in the first clause, then layered constraints and the one-time-secret warning, then the UI mirror and permission note. Dense but every sentence carries actionable information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by saying exactly what the answer carries (the link) and that it is not retrievable later. Combined with the server and Admin preconditions, an agent has everything needed to call and handle the result 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 five parameters; the description nonetheless adds meaning, notably that traits decide which audiences the identity joins, plus a concrete example ({"kind": "agent"}) and the newIdentity/identity interaction. It mostly reinforces rather than extends the schema, so it sits just 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?
States a specific verb and resource: mints an access link to a project's MCP server for one identity, with the link's nature (MCP URL whose secret is the credential) spelled out. It is clearly distinguishable from create_api_key and get_mcp_server, and the identity-scoped, no-sign-in behavior is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives prerequisites and context: the server must be on, the identity must already exist in the project (or be made via newIdentity: true), and the caller needs project Admin. It implies but never names the sibling that turns the server on (enable_mcp_server) or the general-purpose alternative create_api_key, so routing is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a project, as New project in the switcher or Settings › Projects does. The slug is derived from the name as the console derives it and never changes; the person becomes project Admin on it. Member and above.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The display name, with at least two letters or digits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, but the description adds non-obvious side effects: the slug is derived from the name and is immutable, and the caller becomes project Admin. These are behavior details the schema and annotations do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, purpose front-loaded, and every clause carries information (UI equivalence, slug rules, resulting role, permission floor). The comma splice is slightly awkward but the density is appropriate.
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 creation tool with no output schema, the description covers purpose, side effects, immutability of the derived slug, and required role. Nothing essential is missing, though a note on what the response contains or duplicate-name behavior would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with 100% schema coverage, so the baseline is 3. The description goes beyond the schema by explaining the name's downstream effect (slug derivation and immutability), though it does not restate the two-character/digit minimum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb+resource ('Creates a project') and anchors it to the concrete UI equivalents ('New project in the switcher or Settings › Projects'), which makes it easy to distinguish from siblings like create_access_group or create_tag. No ambiguity about what the tool produces.
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?
'Member and above' gives a role prerequisite, which is useful invocation context. However, there is no explicit when-to-use/when-not guidance and no routing against neighboring creation tools (e.g., create_access_group, create_api_key), so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds a tag to the organization's vocabulary, as Manage tags does. Lowercase letters, numbers and dashes, 2-40 characters, starting with a letter. Owner and Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The tag's name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond them: the required role (Owner and Admin) and the name validation rules, which tell the agent what will be rejected before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and resource, followed by constraints and role. Compact with no wasted sentences, though the "as Manage tags does" UI reference is slightly indirect phrasing for an API tool.
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 create tool with annotations and no output schema, the description covers purpose, naming rules, and authorization. It does not state duplicate-name behavior (relevant given idempotentHint=true) or the return value, but overall it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage the baseline is 3, but the description adds clear semantics beyond the schema: lowercase letters, numbers and dashes, 2-40 characters, must start with a letter. These validation constraints materially help the agent construct a valid 'name'.
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 ("Adds") and resource ("tag") scoped to "the organization's vocabulary." It is distinguishable from delete_tag, rename_tag, and merge_tags by the additive verb, but it does not explicitly name or contrast those 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 only implied – the description says it adds a tag but gives no explicit when-to-use, when-not-to-use, or alternative (e.g. rename_tag for existing tags). The "as Manage tags does" reference and the Owner/Admin prerequisite are useful context but not routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a group. Mirrors deleting a group on Settings › Roles & access; needs Owner or Admin. Everyone cannot be deleted, and neither can a group a rule still names: change or delete those rules first. Destructive: call without confirm first, put the sentence it answers to the person, and pass confirm: true only if they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | True only once the person has agreed to the deletion. | |
| groupId | Yes | The group's id, as list_access_groups returns it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further by disclosing the authorization requirement, the protected-group constraints, and the exact confirm handshake (call first without confirm, then pass confirm: true only on agreement). This is behavioral context the agent cannot get from the schema or annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the verb and the UI mapping, then layers constraints and the confirm workflow with no filler sentences. The final confirm sentence is dense but every clause carries an instruction the agent needs, so nothing is wasted.
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 destructive, no-output-schema mutation, the definition supplies auth requirements, deletion blockers, and the confirmation flow. Nothing needed to call it safely and 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 baseline is 3, but the description adds real meaning by describing the two-step confirm protocol rather than just the parameter's literal type. It does not clarify the groupId source beyond what the schema field description ('as list_access_groups returns it') already says, keeping it from 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?
States a specific verb+resource ('Deletes a group') and immediately maps it to the concrete UI action it mirrors (Settings › Roles & access), which cleanly separates it from create_access_group, update_access_group, and delete_access_rule in the sibling set.
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 (Owner or Admin) and two explicit exclusions (the Everyone group cannot be deleted; a group a rule still names cannot be deleted until the rule is changed or removed). This tells the agent both when it will succeed and when it must redirect elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a rule; the people it reached lose that access unless a role, another rule or a grant gives it. Mirrors deleting a rule on Settings › Roles & access; needs Owner or Admin. Destructive: call without confirm first, put the sentence it answers to the person, and pass confirm: true only if they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| ruleId | Yes | The rule's id, as list_access_rules returns it. | |
| confirm | Yes | True only once the person has agreed to the deletion. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive and idempotent, but the description goes further by naming what is actually destroyed (access propagation through roles, other rules, or grants), the UI surface it mirrors, and the auth level required. The confirm protocol is behavioral detail the annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose, then consequence, permissions, and the confirm ritual in tight sequence. Every clause carries weight, though the ordering of the confirm instructions is slightly dense for a single long sentence.
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 two-param destructive tool with no output schema, the description covers purpose, side effects, permission gate, and safety protocol. An agent has everything needed to call it correctly and avoid an unauthorized destructive action.
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; the description adds the semantics of the confirm flag beyond the schema's one-liner by describing it as the point of consent after showing the person the consequence sentence. It does not add anything for ruleId beyond the schema's reference to list_access_rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Deletes a rule') and immediately scopes the effect ('the people it reached lose that access unless a role, another rule or a grant gives it'). This separates it cleanly from siblings like preview_access_rule, list_access_rules, and update_access_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the permission requirement (Owner or Admin) and prescribes the call flow: call without confirm first, present the consequence sentence to the person, then pass confirm: true only on agreement. This is a concrete when/how-and-with-what-gate, not an implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a project permanently and revokes every key it holds, as Delete on Settings › Projects does. Destructive: call it without confirm first, put the sentence it answers to the person, and call again with confirm: true only if they agree. The organization's last live project cannot be deleted. Needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | true only once the person has agreed to the sentence an unconfirmed call answered with. | |
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint=true and idempotentHint=true; the description goes well beyond them by disclosing that every key is revoked, that a confirmation round-trip is mandatory, that the last live project is protected, and that Admin rights are required. 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?
Four sentences, front-loaded with the destructive impact and the confirm protocol, with no filler. The confirmation instructions are somewhat wordy but each clause carries actionable 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?
There is no output schema, and the description compensates by explaining that an unconfirmed call answers with a sentence rather than deleting, plus the auth and last-project constraints. Nothing needed to invoke it safely 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 both param descriptions already explain the confirm handshake and the project-slug omission rule. The description restates that same guidance rather than adding format or edge-case detail, so baseline 3 is correct.
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 ('Deletes a project permanently and revokes every key it holds') and differentiates from the sibling archive_project by stressing permanence. The 'as Delete on Settings › Projects does' mapping grounds the semantics in the known UI action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit two-step protocol: call without confirm first, relay the returned sentence to the person, then call again with confirm: true only on agreement. It also names the blocking preconditions (last live project cannot be deleted, requires project Admin), so when-not-to-use is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a tag nothing depends on, as Delete on Manage tags does; a tag a project carries or a rule matches is refused. Destructive: call it without confirm first, put the sentence it answers to the person, and call again with confirm: true only if they agree. Owner and Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| tagId | Yes | The tag's id, exactly as list_tags returned it. | |
| confirm | Yes | true only once the person has agreed to the sentence an unconfirmed call answered with. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, yet the description still adds substantial behavior: the dependency-based refusal rules, the mandatory confirm sequence, and the required role. That is exactly the kind of context annotations cannot carry.
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 dense sentences with no filler, and the destructive warning is front-loaded. The phrasing 'put the sentence it answers to the person' is slightly awkward and costs a little clarity, but nothing is wasted.
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 two-parameter destructive tool with no output schema, the description covers purpose, refusal conditions, the confirm protocol, and authorization. An agent has everything needed to call it safely and 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 both tagId and confirm are already fully documented in the schema, including the meaning of confirm. The description's confirm language largely mirrors the schema rather than adding new parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Deletes a tag') and immediately bounds the scope ('nothing depends on' it), plus the refusal condition. It names the sibling surface it mirrors ('as Delete on Manage tags does') and implicitly separates itself from merge_tags/rename_tag/delete_project. An agent can distinguish it without opening another schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use and when-not: only tags with no dependents; tags carried by a project or matched by a rule are refused. It also prescribes the exact two-call confirm workflow and names the authorization gate (Owner and Admin), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turns a project's end-user MCP server on and answers with its address, which is derived from the organization and project slugs, so there is nothing to choose. A server that was on before takes back the same address. Nobody can sign in until the project has a login connection (set on Build › MCP server) or an access link (create_mcp_access_link). Mirrors Build › MCP server › Enable MCP server; needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: it discloses that the address is derived from org/project slugs and is not configurable, that re-enabling an already-on server returns the same address (the practical meaning of idempotentHint), and that project Admin permission is required. These are non-obvious operational facts 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?
Front-loads the action and its outcome, then covers idempotency, prerequisites, UI mirror, and permission. Mostly earns its sentences, though 'which is derived from the organization and project slugs, so there is nothing to choose' is slightly wordier than needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing the return (the server address and its derivation). Combined with permission and sign-in prerequisites, an agent has everything needed to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already explains the slug format and the omit-when-single-project rule. The description only adds that the address derives from organization + project slugs, which is marginal 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?
States a specific verb and resource ('Turns a project's end-user MCP server on') and even names the return value (the server address). It is clearly distinguishable from siblings like get_mcp_server (read) and create_mcp_access_link (prerequisite step).
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 preconditions: nobody can sign in until the project has a login connection or an access link from create_mcp_access_link, and notes project Admin is required. It points at the alternative tool for the prerequisite case, but does not explicitly say when to prefer other server-management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cut files into the data points past reads best and price them, before anything is sent. Each file is detected as email, chat, transcript, table, records, code, documentation or notes (or pass kind to skip detection), cut at its natural boundaries, ordered by time and batched for POST /api/v1/ingest/batch. Answers the points (at most 200, with a preview each), the batches with their idempotency keys, the credits, the balance, and fitsFirst: how many points in order fit what is left. Writes nothing, spends nothing, and leaves no row in the request log. Mirrors the API Explorer's drop review; needs project Read on the project.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | The files, as text: each with its path inside the import (the extension helps detection), its content, and optionally a kind (email, chat, transcript, table, records, code, documentation, notes). Extract PDF or office text yourself first. | |
| points | No | "summary" (the default) lists the points with a preview; "none" lists only files and batches. | |
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| timeZone | No | IANA time zone reading times the files write without one, for example Europe/Paris. UTC when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, yet the description adds material beyond them: no credits are spent, no row is left in the request log, project Read is required, and the response shape (points capped at 200 with previews, batches with idempotency keys, credits, balance, fitsFirst) is spelled out. This is exactly the extra behavioral context that annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then details, then the no-write guarantees, with essentially no filler sentences. The single dense paragraph is information-rich but heavy, and the opening phrase ('data points past reads best') is slightly awkward, keeping it short of 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?
There is no output schema, so the description carries the return-value burden and does so explicitly (points, batches, credits, balance, fitsFirst). It also discloses the auth requirement and the non-mutating guarantee. Nothing needed 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?
Schema coverage is 100%, so all four parameters are already documented in the schema, including the kind enum and the project slug. The description restates the detectable kinds and hints at the ordering/timeZone behavior but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: cutting files into data points and pricing them as an estimate before anything is sent. It names the endpoint it mirrors (POST /api/v1/ingest/batch) and clearly separates itself from siblings like explain_ingestion or retry_ingestion. An agent knows this is a dry-run cost/point estimate, not an actual write.
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?
"before anything is sent" plus "Writes nothing, spends nothing" gives a clear condition for using it (preview/estimate prior to ingesting). It provides strong context but never names the alternative write tool to use once the estimate is accepted, so the when-not/when-to-ingest-anyway half is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where one ingestion stopped and what to do: its phase (queued, processing, captured, indexed, failed, nothing-changed), why it stopped and whether a retry can fix it when it failed, each data point it carried with whether it is searchable and how many memories came out of it, and one sentence naming the next step. Start here when data does not show up. Name the ingestion by its id (the ingest answer's ingestionId) or by the request id that carried it. Needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| requestId | No | The request id (req_…) of the ingest call, when the ingestion id is not known. | |
| ingestionId | No | The ingestion id, as the ingest call answered it or list_requests listed it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's main added value is the auth requirement ('Needs project Read') and the full return contract. Because there is no output schema, describing what the explain actually yields (phase vocabulary, retry determination, per-data-point searchability) is genuinely load-bearing. It does not address rate limits or failure modes of the call itself.
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?
Every clause earns its place — the long first sentence is a justified enumeration of outputs that would otherwise need an output schema, and the trailing sentences handle routing and auth. It is somewhat dense and the 'Start here' cue is buried mid-paragraph rather than front-loaded, which slightly weakens scannability.
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 and no required parameters, the description fully compensates: it defines the return contract, the two identification paths, the auth requirement, and the entry-point condition. An agent has everything needed to select and call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's 'by its id (the ingest answer's ingestionId) or by the request id that carried it' restates the alternation the schema already documents ('when the ingestion id is not known') and adds no retrieval syntax or precedence rule beyond it.
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 ('explain') and resource ('one ingestion'), then enumerates the exact diagnostic content returned: phase, stop reason, retry viability, per-data-point searchability, memory counts, and next step. This clearly separates it from siblings like retry_ingestion, estimate_ingestion, and get_request, which an agent can distinguish 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?
'Start here when data does not show up' is an explicit triggering condition, and the retry-viability output implicitly routes the agent toward retry_ingestion. It also states the prerequisite ('Needs project Read') and the two ways to identify the target. It stops short of naming a sibling alternative or an explicit 'do not use this when' case, so it is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Memories and sources matching a search, newest first, in two paged groups: a source matches on its text and its data point id, a memory on its own words and on an artifact id. Pass ingestionId to list the sources one ingestion carried and the memories drawn from them. Each entry's id is what get_lineage and get_timeline take. Mirrors Trace's root picker; needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| first | No | Entries per group, 1 to 50; 25 when omitted. | |
| search | No | Text, a data point id or an artifact id. | |
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| ingestionId | No | Narrow both groups to what one ingestion carried. | |
| afterSources | No | The sources group's endCursor from the previous page. | |
| afterMemories | No | The memories group's endCursor from the previous page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real context the annotations do not: newest-first ordering, that results come back as two independently paged groups, the permission requirement ('needs project Read'), and the picker it mirrors. The only omitted traits are page-size limits and empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, no filler, front-loaded with the core result description and then the matching rules and the ingestionId narrowing. It is dense and heavily compressed, but every sentence carries distinct information; the two-group semantics could have been slightly clearer without adding length.
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?
This is a read tool with no output schema, so the description must carry the return-shape burden, and it does reasonably well: it discloses the two paged groups, ordering, the two per-group cursors (matching afterSources/afterMemories), and that ids are the follow-on handle. Only the page-size cap and default are left to the schema, which already states them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 and the schema already documents each parameter. The description nonetheless adds semantics beyond the schema by explaining what the search term actually matches against for each group and how ingestionId narrows both groups simultaneously. It does not, however, clarify cursor pairing behavior across the two groups beyond what the schema field names imply.
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 concrete verb-resource: returns 'memories and sources matching a search' in two paged groups, and specifies what actually matches (source text/data point id, memory words/artifact id). It also differentiates itself downstream by naming get_lineage and get_timeline as consumers of each entry's id. It does not, however, distinguish itself from near-siblings like recall_memory or explain_ingestion, which also surface memory content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is one conditional usage note ('Pass ingestionId to list the sources one ingestion carried and the memories drawn from them') and a chaining hint ('Each entry's id is what get_lineage and get_timeline take'), both useful. But no guidance is given on when this tool is the right choice versus recall_memory, explain_ingestion, or list_requests, so usage is mostly implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The organization's credits left, the included and bought credits, the reset date, and one project's month: credits spent, ingestions, recalls, and what is left of its credit and ingestion caps. Use it when an ingestion is refused with 402 (out of credits) or 429 project-cap-reached. metered is false on a self-hosted deployment with no plan, and the credit figures are then null. Answers what GET /api/v1/usage answers for a project key; needs project Read on the project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real context beyond that: the required 'project Read' permission, the self-hosted edge case where metered is false and credit figures are null, and the error codes that motivate the call.
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 response contents are front-loaded in the first sentence, followed by the use case and then caveats. It is dense and slightly run-on but each sentence carries information an agent needs; nothing is 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?
With no output schema, the description carries the burden of describing return values, and it does list the main fields. It also covers permission requirements and a deployment edge case. The default time window ('its month' = current month) and any paging/limits are left implicit, so it is not fully exhaustive.
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% for the single 'project' parameter, and the description adds no syntax, format or validation detail beyond what the schema already states. Baseline 3 applies when the schema does the heavy lifting.
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 resource (organization credit balance plus one project's monthly spend/ingestion/recall figures) and enumerates exactly which fields come back, including the included vs. bought credit split and remaining caps. An agent can tell this apart from generic siblings like get_usage or get_plan because the scope (org credits + a single project's month) is stated 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?
It gives a concrete trigger: 'Use it when an ingestion is refused with 402 (out of credits) or 429 project-cap-reached.' That is a clear when-to-use condition rather than implied usage. It stops short of naming a sibling alternative to prefer in other situations, so it is not a full when/when-not/alternatives statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a memory was built from and what was built on it: the nodes reachable from the root and the edges among them (each edge reads: derivedId was built from inputId), with how many the limit left out. Walks every side by default. Mirrors Trace's Lineage tab; needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | The most nodes to return, 1 to 400; 50 when omitted. | |
| reveal | No | Sides to open when revealAll is false, each "<id>:inputs" or "<id>:outputs". | |
| rootId | Yes | The root's id: a memory or a source. | |
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| revealAll | No | Walk every side up to the limit. True when omitted; false walks only `reveal`, or the root's inputs when that is empty. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context on top: the required permission ('project Read'), the default walk-every-side behavior, and notably the truncation disclosure ('with how many the limit left out'), which tells the agent results may be partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what is returned before the permission note. The edge-reading parenthetical and truncation clause each add distinct value. Slightly dense, but nothing reads as 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?
With no output schema, the description carries the return-value burden and does so: it describes nodes, edges, edge direction, and truncation count, plus the auth requirement. Missing only ordering/pagination detail for the returned nodes, which would fully close the loop.
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 earns above it: it explains the edge reading convention ('derivedId was built from inputId'), which is response semantics for the graph, and clarifies the default traversal ('Walks every side by default') that governs revealAll/reveal behavior without restating 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+resource: the memory's lineage, split into upstream ('what a memory was built from') and downstream ('what was built on it'), plus the exact edge semantics ('derivedId was built from inputId') and the limit-truncation count. That is far more than a restatement of the name. It does not name a sibling (e.g. get_trace_node, find_trace_roots) to contrast against, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied by 'Mirrors Trace's Lineage tab', and the prerequisite 'needs project Read' is given, along with the default traversal behavior. But there is no explicit when-to-use guidance versus the trace-node/root-finding siblings, so the agent must infer the routing decision itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the organization's management key called in the last 30 days: each route with its method, call count and last call, busiest first; a route nobody called is absent. Mirrors Settings › Management key › Recent activity; needs Owner or Admin.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, but the description adds substantive detail beyond them: the 30-day window, sort order (busiest first), the filtering rule that uncalled routes are absent, the returned fields, and the Owner/Admin auth requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-structured sentence using a colon to enumerate the return fields, front-loaded with what the tool answers. Dense but every clause carries information; only slightly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining the return shape, and it does — route, method, call count, last call, ordering. Auth needs and the absence-of-data rule are also covered, leaving nothing 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?
The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering inputs are needed and frames the scope as fixed, adding what meaning there is to convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — the organization's management key activity — with an explicit 30-day scope. An agent can immediately distinguish this from get_organization, get_usage, or get_credit_balance without inspecting 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?
Gives clear context: it mirrors Settings › Management key › Recent activity and requires Owner or Admin. This tells the agent who can call it and what it corresponds to in the UI, though it names no alternative tool for related questions (e.g., general API usage).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A project's end-user MCP server, as Build › MCP server shows it: whether it is on, its address (while it is off, the address it would take), whether end users may write, the login connection, the live access links and whether anybody can sign in yet. Needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value beyond that: the Admin authorization requirement and the semantic detail that the address shown while off is 'the address it would take', which clarifies the returned value's meaning.
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 content is front-loaded (what the tool returns) followed by the prerequisite. It is a single dense sentence plus a short sentence, with no wasted clauses, though the colon list makes it slightly run-on.
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 usefully enumerates what the response contains (on/off state, address, write permission, login connection, access links, sign-in status), which compensates for the absent output schema. Combined with the Admin note, an agent has enough to call it correctly; only return formatting details are 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 single 'project' parameter is well documented in the schema (slug format, when it can be omitted). The description adds nothing about the parameter, 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?
The description states a specific verb (shows) and resource (a project's end-user MCP server) and enumerates the fields returned, making it clearly a read/config-inspection tool. It does not explicitly differentiate itself from siblings like enable_mcp_server or create_mcp_access_link, but the enumeration of state ('whether it is on') implies viewing rather than mutating.
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 a prerequisite ('Needs project Admin') which is useful context for when the call will succeed, but gives no explicit when-to-use vs when-not guidance or naming of alternatives. The read-only nature is implied by the title and field list rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The organization: name, slug, plan, creation date and member count. Mirrors Settings › General; every role holds it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, non-destructive and closed-world behavior, so the bar is low. The description still adds real value by disclosing the permission profile (accessible to every role) and by naming the fields returned, which the annotations do not 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?
Two compact clauses with the resource named first and supporting details second, so it is front-loaded and free of filler. It reads slightly as a field dump rather than a sentence, which keeps it just short of ideal.
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-param read with full annotation coverage and no output schema, the description supplies the returned fields and the access scope an agent would otherwise have to guess. Nothing critical is missing, though it could note how it relates to the overlapping get_plan/get_viewer siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. No syntax, ordering or filtering caveats are needed for a no-arg getter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (the organization) and enumerates the fields it surfaces (name, slug, plan, creation date, member count), which distinguishes it from sibling getters like get_plan and list_members. It never uses an explicit retrieval verb, so the read nature is only implied, but the scope is 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?
"Every role holds it" gives useful access context and "Mirrors Settings › General" locates it conceptually, but there is no explicit when-to-use guidance or routing versus alternatives such as get_plan or get_viewer, both of which overlap on org-level data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The organization's plan: the credits it includes and whether they come back each billing period or were granted once, how many content bytes buy a credit, what one recall costs, any cap on recalls, how long request payloads are kept, how long unused credits roll over, and what happens when the credits run out. Mirrors the plan the Usage screen and the sidebar meter show; every role holds it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new context: it is accessible to every role (no auth gating) and it mirrors the values shown in the Usage screen and sidebar meter, telling the agent the data is presentation-consistent. No return format or size hints beyond that, but the annotation floor is already low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the subject ('The organization's plan') before the enumeration, and it caps off with a useful consistency note rather than trailing off. The single sentence is long and comma-heavy, but each listed item is a distinct plan attribute, so nothing is 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?
With no output schema, the description has to carry the return-value burden, and it does: it lists credits, rollover behavior, byte-to-credit ratio, recall cost, recall cap, payload retention, and overage behavior. That is close to a field-level summary. The remaining gap is that it never states the response shape or whether values are static per billing period.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the field enumeration describes contents rather than arguments, which is the correct use of space here.
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?
It names a specific resource (the organization's plan) and enumerates precisely what that plan covers — credits, rollover, caps, payload retention. The title supplies the verb. It doesn't explicitly distinguish itself from close siblings like get_credit_balance or get_usage, though 'Mirrors the plan the Usage screen and the sidebar meter show' partly does that work.
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 implied — call it to inspect plan terms — but there is no explicit when-to-use guidance and no mention of the obvious alternatives (get_credit_balance, get_usage) that an agent might confuse with it. The closing note that 'every role holds it' rules out a permission gate, which is the only real guidance offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One project in full, as the Settings › Projects drawer shows it: its row, and the Access tab listing who reaches it, at what level, through their role, a rule or a grant, and until when. Needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish a safe, read-only, idempotent, non-destructive, closed operation, so the safety profile is fully covered. The description adds valuable behavioral context by specifying the return contents (project row plus access details) and the required permission, 'Needs project 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?
Two sentences, front-loaded with the core purpose and followed by the permission requirement. Every phrase adds useful scope detail, and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully explains what is returned: the project row and Access tab details. The single parameter is fully documented in the schema, and the annotations cover safety. It is complete for a read tool, though it could mention error behavior or empty results for full coverage.
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 description already explains that the slug must match what list_projects returned and that it may be omitted only when the organization has one live project. The tool description adds no further parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope: 'One project in full' including its row and Access tab details. It clearly contrasts with a list tool by returning one project, but it does not explicitly distinguish itself from siblings like get_project_access or list_projects, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance or mention of alternatives. 'One project in full' implies retrieving a single project's full details, but it does not say when this should be chosen over list_projects or get_project_access. 'Needs project Read' is an authorization note, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who reaches one project: each person with their level, where it comes from (Role, Rule or Grant), the rule's name when a rule gives it, and when it lapses. Mirrors the Access tab of a project on Settings › Projects; needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug; omitted, the organization's only live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: the required project Read permission and a breakdown of what the response contains (grant sources, rule names, lapse timing). It doesn't mention pagination, but for a per-project access listing that is minor.
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 tight sentences, front-loaded with the core purpose and followed by the return shape and permission requirement. Every clause carries information; nothing is 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?
With no output schema, the description carries the return-value burden and does so well by enumerating what each row includes. Combined with the permission prerequisite, an agent has everything needed to call and interpret this read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is fully documented there, including the null default behavior (fall back to the org's only live project). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise resource and scope ('Who reaches one project') and enumerates the returned detail (level, source of Role/Rule/Grant, rule name, expiry). This is clearly distinct from mutation siblings like grant_project_access or revoke_project_grant, though it never names an alternative tool 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?
It anchors usage to a familiar surface ('Mirrors the Access tab ... on Settings › Projects') and states the prerequisite ('needs project Read'), giving the agent clear context for when this tool applies. It stops short of naming when-not-to-use or pointing at grant/revoke siblings for changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One call from a project's request log, as the Requests detail drawer shows it: method, path, status, the request id, when it arrived, how long it took, the key, the outcome and phase, what it was billed, and the allowlisted headers with the request and response bodies. Past the plan's retention window the row stays and the payload is gone. Mirrors the Requests detail screen; needs project Read on the project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| requestId | Yes | The request id (req_…), exactly as list_requests returned it or as the X-Request-Id header carried it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: the retention-window caveat that the row persists but the payload is gone, and the project Read authorization requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core idea in the first clause, then the return-field enumeration, a caveat, and the prerequisite. The field list is long and somewhat run-on, but every item is informative for an agent with no output schema, so it 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?
With no output schema, the description carries the return-value burden and does so thoroughly by enumerating the returned fields, plus it covers the retention edge case and the permission requirement. Nothing an agent needs to invoke or interpret this read call 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 both parameters (project and requestId) are already fully documented in the schema, including the slug format and the req_ id format. The description does not add syntax or format detail beyond that, making the baseline 3 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 names a specific verb+resource ('One call from a project's request log') and immediately distinguishes itself from the plural sibling list_requests by scoping to a single request detail view. It also enumerates the payload fields, so an agent knows exactly what this returns versus broader log queries.
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 implied through 'as the Requests detail drawer shows it' and 'Mirrors the Requests detail screen,' and the stated 'needs project Read' prerequisite is useful context. However, it never explicitly names when to pick this over list_requests or request_histogram, and gives no exclusions, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The work around a root on a clock: every node reachable from it with when it occurred, arrived and became searchable, sectioned as revision, built-from, produced or elsewhere; the ingestions in the window that carried its sources, with their phase; the recalls in the window that returned one of the nodes; and which node replaced which. The window is at most 31 days, the root's recent history by default. Mirrors Trace's Timeline tab; needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the window, ISO 8601. | |
| from | No | Start of the window, ISO 8601. | |
| rootId | Yes | The root's id: a memory or a source. | |
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds genuine behavioral facts: a hard 31-day window cap, default-to-recent-history behavior, and a required project Read permission. What it omits is ordering/pagination behavior and what happens when the root has no reachable nodes.
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?
One long semicolon-chained sentence whose lead clause is the least comprehensible part of the text, so it is not front-loaded. Information density is high and there is little filler, but the structure actively impedes parsing the most important statement.
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 and four parameters, the description carries the return-value burden and largely meets it, naming the sections (revision, built-from, produced, elsewhere) plus ingestions, recalls and replacement edges. Auth requirements and the window default are also covered; only ordering and edge-case behavior are 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 would be 3; the description earns above that by supplying the 31-day maximum for from/to and the default window semantics, which the schema does not state. It adds no extra meaning for project beyond the schema, but the window constraint is real parameter-level information.
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 does enumerate what comes back (reachable nodes with timestamps, ingestions, recalls, replacement edges), so the resource is identifiable as 'the history around a root node'. However the opening framing 'The work around a root on a clock' is cryptic rather than a clean verb+resource statement, and it never distinguishes this from adjacent tools like get_lineage, get_trace_node or find_trace_roots that also operate on trace roots.
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 a usable constraint ('window is at most 31 days, the root's recent history by default') and a prerequisite ('needs project Read'), plus the anchoring cue 'Mirrors Trace's Timeline tab'. But it gives no explicit when-to-use versus get_lineage or get_trace_node, which is the real selection decision an agent faces among these siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One memory or source by its id: its headline, kind, data point and revision, when it occurred, arrived and became searchable, its validity, whether it is current, and how many inputs and outputs it has. A source carries its text, cut to 4,000 characters. Mirrors Trace's sheet; needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id, exactly as find_trace_roots, get_lineage or explain_ingestion returned it. | |
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the authorization requirement ('needs project Read'), the 4,000-character truncation applied to source text, and the fact that the payload mirrors the Trace sheet. Missing only pagination/error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core scope, then the returned fields, then the truncation caveat and auth requirement — no filler sentences. The field enumeration is dense and slightly run-on, but every clause carries information an 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?
With no output schema, the description carries the full burden of describing returns and does so thoroughly, including truncation of source text; it also flags the read-permission requirement. It stops short of covering not-found/cross-project id behavior, but it is otherwise sufficient for a two-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both 'id' and 'project' are fully documented in the schema itself (including the single-live-project default). The description adds only the framing 'by its id', so the baseline 3 for schema-driven parameters is correct.
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 precise resource and scope ('One memory or source by its id') and then enumerates exactly what the node contains — headline, kind, data point, revision, timestamps, validity, currency, and input/output counts. That field inventory plainly separates it from lineage- or roots-oriented siblings like get_lineage and find_trace_roots without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the id is described in the schema as coming from find_trace_roots, get_lineage or explain_ingestion, and the description adds the 'needs project Read' prerequisite. It never states when to pick this over those sibling retrieval tools or when the call would fail. Adequate but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This billing period's usage (UTC): credits spent against the credits included, split by what spent them — ingesting content, receiving webhook events and serving recalls — with ingestion and recall counts, each project's credits and share, and the date the included credits reset. Mirrors the Usage screen's balance and its By project table; Owner, Admin and Billing hold it. Reading usage spends no allowance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description correctly spends its words elsewhere: it discloses required roles and that the call is free of allowance spend. It does not describe pagination or output format, but for a zero-param read tool the added permission and cost disclosure is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads what is returned, then permissions, then the cost caveat. Every clause carries information, though the enumeration of return fields is long enough that slightly tighter phrasing would help.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of describing the payload, and it enumerates the balance, per-project shares, counts, and reset date thoroughly. Combined with the permission and cost notes, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is nothing to disambiguate; the baseline for zero-param tools applies and the description appropriately focuses on interpreting the result instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource with unusual depth: it names the reporting period (UTC billing period), the split dimensions (ingestion, webhook events, recalls), the per-project breakdown, and the reset date. An agent can distinguish this from sibling get_credit_balance (point balance) and get_plan without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States access conditions (Owner, Admin, Billing) and the important cost caveat that reading usage spends no allowance, which is exactly the when-relevant context for a metered product. It stops short of explicitly naming when to prefer it over get_credit_balance or get_plan, so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who you act for: name, email, platform role, the organization, and every live project they reach with the level they reach it at. Call it first. Every role holds it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, closed-world, non-destructive behavior, so the bar is lower. The description adds a genuine behavioral fact beyond annotations: the tool is available to every role regardless of privilege.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the return contents, followed by the actionable 'Call it first' and the access note. Slightly flowery phrasing ('Who you act for', 'the level they reach it at') but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description carries the load of describing return values and does so by enumerating identity fields and reachable projects. No parameters and no annotations gaps leave little else to cover, though the notion of project 'level' could be more precise.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the baseline this scores 4. There is nothing for the description to disambiguate regarding inputs.
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 specifies what comes back (name, email, platform role, organization, and reachable projects with access level), so an agent understands this returns the current signed-in identity rather than org-wide or member data. It never states the verb 'get/return' explicitly, framing it as 'Who you act for,' but the content list is specific enough to separate it from get_organization and list_members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call it first' is an explicit sequencing directive, and 'Every role holds it' tells the agent that no permission gating applies. There is no named alternative or when-not condition, but the primary usage context is clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grants one member direct access to one project at Read, Write or Admin, optionally until a date; granting again replaces their grant. Mirrors Grant access on a project's Access tab; needs project Admin on that project. Owners and Admins already reach every project and Billing none, so they cannot be granted.
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | Read, Write or Admin. | |
| userId | Yes | The member's userId, as list_members or get_project_access returns it. | |
| project | No | The project's slug; omitted, the organization's only live project. | |
| expiresAt | No | When the grant ends, as an ISO 8601 date or time in the future; omitted, it never does. A date already past is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it explains that 'granting again replaces their grant' (the concrete destructive/idempotent behavior behind destructiveHint+idempotentHint), that the grant can be time-boxed via 'optionally until a date', and that the caller must hold project Admin. This is a mutation tool whose safety profile, replacement semantics and auth requirement are all disclosed.
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 clause, followed by semantics, prerequisite and exclusions in a tightly packed three-sentence block. Dense but every clause carries information; a minor cost is the semicolon-linked length of the opening sentence.
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 4-parameter mutation tool with a fully documented schema and no output schema, the description supplies the missing behavioral layer: permission requirement, replacement semantics, expiry behavior and who cannot be granted. 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 coverage is 100%, so all four parameters already carry descriptions covering level values, userId source, the project slug default and the ISO 8601 expiresAt with past-date refusal. The description restates level and expiry but adds no syntax or default behavior beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and scope: 'Grants one member direct access to one project at Read, Write or Admin'. The cardinality (one member, one project) and the level set make it distinguishable from siblings like revoke_project_grant, set_member_role and create_access_rule 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?
Gives the precondition explicitly ('needs project Admin on that project') and an exclusion rule ('Owners and Admins already reach every project and Billing none, so they cannot be granted'), which prevents predictable failed calls. It does not name alternative routes such as create_access_rule for group-based access, so the when-to-use-vs-alternatives dimension is slightly incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingests one data point into a project's memory, as POST /api/v1/ingest does, and answers as it does: the ingestion id, the source id and the status. With no audience the data point is for the whole project; name an audience by its slug to keep it to that audience. An id that already exists replaces the earlier revision and the memories that came from it, and the same content under the same id is unchanged and costs nothing. It spends the project's credits as an API ingestion does. Ingest only what the person asks you to keep. Needs project Write.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Your own id for this data point. Send it again to replace the earlier revision. When omitted, the id comes from the content. | |
| label | No | A short title for the data point, such as "Email from Nadia". When omitted on a re-send, the stored label stays. | |
| content | Yes | The text to keep, as the person gave it. | |
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. | |
| audience | No | The slug of an audience that exists in the project, to keep the data point to that audience. Omit it for the whole project. | |
| identity | No | The author: the customer's own id for one of their users. Its first appearance creates it in the identity directory. | |
| metadata | No | Your own JSON, stored and returned as sent. Keys such as role, author, conversationId and messageId help past attribute and order what it reads. | |
| timestamp | No | When the data point happened (ISO 8601). Now when omitted, or the stored time on a re-send. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it explains idempotency mechanics (same content under same id is unchanged and costs nothing), replacement semantics (an existing id replaces the prior revision and its derived memories), credit spend, and the required Write permission. This is exactly the behavioral context an agent needs for a mutating, destructive-capable tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and return shape, then each sentence carries a distinct concern (scope, id behavior, credits, guidance, permission). It is somewhat dense and clause-heavy, but no sentence is wasted.
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 discloses the response contents (ingestion id, source id, status), plus auth requirement, credit implications, and scoping behavior. An agent has enough 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%, so the schema already documents all eight parameters thoroughly. The description reinforces id replacement, audience scoping, and timestamp defaults but adds little semantic detail beyond what the schema provides; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Ingests one data point into a project's memory') and clarifies the operational analogue (POST /api/v1/ingest). It does not explicitly differentiate from siblings like estimate_ingestion, explain_ingestion, or retry_ingestion, so an agent must infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear usage constraint ('Ingest only what the person asks you to keep') and notes that it spends project credits, which helps the agent decide relevance. It stops short of naming alternative tools (e.g., estimate_ingestion) or explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invites an email address into the organization at a platform role, with the person you act for as the inviter. Mirrors Settings › Members › Invite member; needs Owner or Admin. The role is Admin, Member or Billing: Owner is refused, because ownership moves by set_member_role once they have joined. Project access is left to rules and grants. Where no mail goes out the answer carries the single-use link: give it to the person you act for and nowhere else.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | Admin, Member or Billing. | |
| Yes | The address to invite. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds the auth requirement, the role-restriction behavior, that project access is deferred to rules/grants, and that a single-use link is returned and must be kept secret. That is substantial context beyond the annotations, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and scoped well, but it is one dense paragraph and some phrasing ('with the person you act for as the inviter') is heavy. Still, nearly every clause carries information an 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?
For a 2-param mutation with no output schema but full annotation coverage, the description supplies purpose, auth, role constraints, alternative routing, and the notable return value (single-use link). Nothing essential to calling it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description adds real meaning: the valid role values (Admin, Member, Billing) and the critical exclusion that Owner is refused. That goes beyond the terse schema 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?
States a specific verb and resource ('Invites an email address into the organization at a platform role') and pins scope to a platform role rather than project-level access. This clearly separates it from siblings like list_members, resend_invitation, and set_member_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?
Gives the UI analogue (Settings › Members › Invite member), the prerequisite ('needs Owner or Admin'), and explicitly routes the ownership case elsewhere ('ownership moves by set_member_role once they have joined'). Both when-to-use and the relevant alternative are spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The organization's groups: name, whether it is the built-in Everyone, its members (userId, name, email, role) and how many rules name it. Mirrors Groups on Settings › Roles & access; needs Owner or Admin.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe, idempotent, non-destructive read. Beyond that, the description adds the real behavioral constraint an agent needs: the call requires Owner or Admin privileges. It also discloses the shape of the returned data, which matters because no output schema exists, but says nothing about pagination or volume limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the content of the response and closed with the UI mapping and permission requirement. It is dense (nested parenthetical field list) but every clause carries information; only minor tightening is possible.
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 parameterless read tool, the description covers what it returns (compensating for the missing output schema) and the permission gate that determines whether the call succeeds. Nothing an agent needs before invoking it is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain; per the baseline this scores 4. The description's enumeration of returned fields instead compensates for the absent output schema, which is the more relevant gap here.
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 the resource (the organization's access groups) and enumerates precisely what each entry contains: name, built-in Everyone flag, members with userId/name/email/role, and rule-reference counts. That content profile separates it from siblings like list_access_rules or list_members, though the listing verb itself is only implied by the tool name rather than stated.
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?
"Mirrors Groups on Settings › Roles & access; needs Owner or Admin" gives a useful applicability condition and permission prerequisite, so an agent knows when the call will succeed. However, there is no explicit guidance about when to prefer this over list_access_rules when investigating access, so usage remains implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The organization's tag-matched access rules: who each names (groups and people), the tags and how they match, the level it gives, when it lapses, the projects it matches today and how many people it reaches. A rule whose expiry has passed is still listed, marked lapsed, matching nothing and reaching nobody. Mirrors Project access rules on Settings › Roles & access; needs Owner or Admin.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds meaningful behavior: lapsed rules remain listed but are marked lapsed, match nothing, and reach nobody. It also discloses the auth requirement (Owner or Admin), which the annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is front-loaded ('The organization's tag-matched access rules') and every clause about returned fields and lapse behavior carries information. The first sentence is a long enumeration, but nothing is redundant and the two-sentence structure is easy to parse.
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 carries the return-value burden, enumerating the fields an agent will receive and explaining the lapsed-rule edge case. Combined with the permission note, an agent has everything needed to call and interpret this zero-parameter read.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. Schema coverage is 100% but moot with an empty properties object.
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) and resource (the organization's tag-matched access rules), then enumerates the exact fields returned: named groups/people, tags and match logic, level, lapse time, matched projects, and reach. This clearly distinguishes it from the sibling list_access_groups, which covers a different resource.
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 the permission prerequisite ('needs Owner or Admin') and locates the concept against the UI ('Mirrors Project access rules on Settings › Roles & access'), which is genuine usage context. However, it never says when to reach for this tool versus list_access_groups, preview_access_rule, or the create/update/delete siblings, so the routing guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A project's live keys, newest first: id, name, masked value, created by, created and last used. Never the clear value of a key, which only the person can reveal on the screen. Mirrors API keys; needs project Admin. Name the project by slug; omit it when the organization has one live project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug; omitted, the organization's only live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description still adds meaningful context: the key value is masked and never returned in clear text, and Admin permission is required. It could note pagination limits or result counts, but the security and permission disclosures are the high-value items.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads scope and ordering before constraints, and every clause carries information (fields, security caveat, permission, slug rule). The phrase 'Mirrors API keys' is slightly opaque, keeping it just short of ideal.
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 compensates by enumerating returned fields (id, name, masked value, created by, created, last used) and the masked-value caveat. Permission requirements and the slug rule complete what an agent needs 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 single 'project' slug parameter is fully documented there. The description restates the same omit-for-single-project rule without adding syntax or format detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (list) and resource (a project's live API keys), plus scope and ordering ('newest first'). It is trivially distinguishable from create_api_key and revoke_api_key among the 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?
Gives clear operational context: it 'needs project Admin' and explains when to pass the slug versus omitting it (organization with a single live project). It does not explicitly name alternatives, but the create/revoke siblings make the boundary self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everyone in the organization: each member's id, userId, name, email, platform role, joined date and the projects they reach ("Every project", "No projects", or a count and its largest source), then the pending invitations. Mirrors Settings › Members; needs Owner or Admin. Use id with set_member_role, remove_member and resend_invitation, and userId with grant_project_access and the access rule and group tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnly/idempotent/non-destructive, the description goes further: it discloses the authorization requirement (Owner or Admin) and that the result also contains pending invitations, not just active members. It also grounds the tool in a known UI location ('Mirrors Settings › Members').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the resource and its returned fields, then auth, then downstream routing — a sensible ordering. It is one very dense passage, and the parenthetical project-reach enumeration could be tightened, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the burden of describing return contents, and it does so in detail (field list, project-reach variants, invitation inclusion) while also covering the auth prerequisite. Nothing needed to call or interpret this 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 tool takes zero parameters, so the baseline is 4. The description instead documents the shape of returned identifiers (id vs userId) and their intended consumers, which is useful but strictly outside parameter 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?
States a specific verb and resource ('Everyone in the organization') and enumerates exactly what is returned — member id, userId, name, email, role, joined date, project reach, plus pending invitations. It is also distinguishable from siblings like list_projects or list_access_groups because it names the exact entities it emits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit prerequisite ('needs Owner or Admin') and concrete downstream routing: 'Use id with set_member_role, remove_member and resend_invitation, and userId with grant_project_access and the access rule and group tools.' That tells the agent both when to call this and which identifier to pass where.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The live projects the person reaches, as Settings › Projects lists them: id, slug, display name, tags, monthly caps with this month's spend, memory count and the level they reach each at. includeArchived adds archived projects for an Owner or Admin and is ignored for a Member. Every role but Billing holds it.
| Name | Required | Description | Default |
|---|---|---|---|
| includeArchived | No | Also list archived projects. Owner and Admin only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds real value beyond that: the role gating ('Every role but Billing holds it') and the important caveat that includeArchived is silently ignored for a Member rather than erroring. No pagination or rate-limit context, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the scope and return payload, then the parameter behavior, then the permission summary. The field enumeration is dense but each item earns its place by telling the agent what comes back in the absence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by listing the returned fields, and it covers parameter semantics, role gating, and the archived-project caveat. For a single-optional-param read tool this is complete enough to call correctly without further inference.
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, and the description adds meaning beyond the schema's 'Owner and Admin only' by clarifying that the flag is ignored for Members (a silent no-op rather than an error). That behavioral nuance justifies exceeding 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 and resource ('list_projects') and then enumerates the exact fields returned (id, slug, display name, tags, caps, memory count, levels), which distinguishes it from get_project and the list_* siblings at a glance. The 'live projects' scope plus includeArchived makes the boundary with archived-project siblings explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear permission-based context: includeArchived is for Owner/Admin, ignored for Member, and every role but Billing can call it. It does not name an alternative tool (e.g., get_project or archive_project) or state when-not-to-use, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One project's request log, newest first, with the Requests screen's filters, search and date range, paged by cursor. Pass endCursor back as after for the next page; use get_request for a call's payload. A range is at most 31 days. Mirrors the Requests screen; needs project Read on the project.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the range, ISO 8601. Defaults to now. | |
| from | No | Start of the range, ISO 8601. Defaults to 24 hours before `to`, the screen's default range. | |
| after | No | The endCursor of the previous page. | |
| first | No | How many calls per page, 1 to 100; 25 when omitted. | |
| search | No | Matches a request id, a key name or a data point id. | |
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| keyNames | No | API key names to keep. | |
| statuses | No | Exact status codes to keep, for example [401]. | |
| endpoints | No | Endpoints to keep, as routed, for example "/api/v1/ingest". | |
| statusClasses | No | Status classes to keep: "2xx", "4xx", "5xx". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive safety profile, so the bar is lower. The description adds valuable operational context: newest-first ordering, cursor pagination, a 31-day range cap, and the project Read authorization requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose and scope, then folds in pagination, alternative tool, range cap, and permissions without bloating. Minor redundancy between 'with the Requests screen's filters' and 'Mirrors the Requests screen' 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 10-parameter tool with no output schema, it covers pagination, permissions, range limits, default range, and the sibling for payloads. It stops short of describing the returned request fields, but the 'use get_request for a call's payload' hint usefully implies the list is summary-level.
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 and the schema carries most parameter meaning. The description still adds value by explaining the cursor handoff for `after` and by constraining `from`/`to` to a 31-day window, which the schema itself does not enforce.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list requests), the scope (one project's request log), ordering (newest first), and that it mirrors the Requests screen. It explicitly distinguishes itself from get_request, which handles a single call's payload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes payload retrieval to get_request, gives the cursor continuation pattern for pagination, states the 31-day maximum range, and names the required project Read permission. An agent knows both how to call it and when the sibling is more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The organization's tags, as Manage tags on Settings › Projects lists them: id, name, how many projects carry each and how many access rules match it. Owner and Admin.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely new context beyond that: the operation requires Owner or Admin privileges and returns aggregate counts rather than bare entities, which tells the agent both the auth requirement and the payload shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the resource and then lists the returned fields, with the role requirement compressed to two words at the end. 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?
With no parameters and no output schema, the description compensates by enumerating the return fields and stating the permission gate, which is enough for an agent to call it correctly. It lacks only a note on ordering or volume (e.g. pagination), a minor gap for a simple list 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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema is empty and fully covered.
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 the resource (the organization's tags) and, through the enumerated fields (id, name, project counts, access-rule match counts), makes clear this is a read/list operation. It is distinguishable from create_tag, delete_tag, rename_tag and merge_tags, though it never explicitly contrasts itself with those 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 only implied: the tool obviously enumerates all tags, and 'Owner and Admin' signals the required role. There is no explicit statement of when to reach for this versus list_projects or list_access_rules, nor any exclusion, so guidance stays at the minimum-viable level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merges one tag into another, as Merge on Manage tags does: the projects carrying it carry the other, the rules matching it match the other, and it is gone. This usually widens who reaches what. Destructive: call it without confirm first, put the sentence it answers to the person, and call again with confirm: true only if they agree. Owner and Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | true only once the person has agreed to the sentence an unconfirmed call answered with. | |
| fromTagId | Yes | The id of the tag that goes away. | |
| intoTagId | Yes | The id of the tag that stays. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive=true/non-readOnly, but the description goes well beyond them by explaining what is destroyed and merged, warning that the merge 'usually widens who reaches what', and mandating a confirmation round-trip. The permission requirement (Owner and Admin) is extra context annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the merge semantics before the destructive workflow warning. Slightly tangled phrasing ('put the sentence it answers to the person') costs a little, but nothing is wasted.
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 destructive, no-output-schema tool this covers effect, side effects on access breadth, confirmation protocol, and authorization level. An agent has everything needed to call it safely without a return-value section.
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 describes fromTagId/intoTagId/confirm in equivalent terms, so the description adds little parameter detail beyond restating the confirm workflow ('the sentence it answers to'). Baseline 3 is appropriate when the schema carries 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 specific verb+resource (merge one tag into another) and then spells out the exact consequences: projects carrying the source carry the target, rules matching it match the target, and the source is gone. This clearly distinguishes it from rename_tag and delete_tag among 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?
Gives an explicit two-step protocol ('call it without confirm first ... call again with confirm: true only if they agree') and names the required role ('Owner and Admin'). When-to-use and the guard condition are both stated rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which live projects and which people a rule would match if it were saved as described. Nothing is written. Mirrors the preview in the New rule drawer on Settings › Roles & access; needs Owner or Admin. People whose role already decides their reach (Owner, Admin, Billing) are left out, because the rule moves nothing for them.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | The tags to match; required unless match is Every. | |
| match | Yes | All (the project carries every tag), Any (at least one), or Every (every live project, whatever it carries). | |
| userIds | No | People by userId, as list_members returns it. | |
| groupIds | No | Group ids, as list_access_groups returns them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, but the description adds real behavior: an auth requirement (Owner or Admin) and a result-shaping exclusion (Owner, Admin, Billing are omitted because the rule changes nothing for them). These are details an agent cannot get from the annotations or schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with what is returned and that nothing is written, then grounding and the exclusion rule. 'Nothing is written' partly echoes readOnlyHint but is short and clarifying; overall there is little wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only preview with full schema coverage and no output schema, the description explains the return conceptually (matching projects and people) and notes a non-obvious output caveat (excluded roles). Nothing needed to invoke or interpret it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents match, tags, userIds, and groupIds (including cross-references to list_members and list_access_groups). The description adds no per-parameter syntax or constraints beyond the schema, so the baseline 3 holds.
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 defines the operation concretely: it returns which live projects and people a rule would match, and clarifies nothing is saved. Combined with the read-only nature, an agent can distinguish it from create_access_rule/update_access_rule. It opens with a noun clause rather than a verb+resource, so it leans on the title, but the intent 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?
It gives clear context for when this applies: a pre-save check ('if it were saved as described') that mirrors the New rule drawer, and states the prerequisite (needs Owner or Admin). It does not explicitly name create_access_rule as the follow-on, so the alternative routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recalls from one project's memory, as POST /api/v1/recall does: the same arguments, the same refusals and the same answer, each result with its sources. With no identity it reads what the console's Memories screen shows: everything in the project. With an identity it reads as that identity: what the whole project sees, and the audiences that hold the identity. It spends the project's credits where the plan prices a recall, as an API recall does. Needs project Read.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | The order of the results after they are chosen: relevance (the default) or chronological. | |
| level | No | The evidence budget in words: low (8,000 tokens, the default), medium (16,000), high (24,000) or extra-high (32,000). Send this or maxTokens, never both. | |
| limit | No | How many results at most, 1 to 200. 100 when omitted. | |
| query | Yes | What to look for, in plain words. | |
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. | |
| identity | No | Read as this identity: the customer's own id for one of their users. Omit it to read everything in the project, as the Memories screen does. | |
| maxTokens | No | The evidence budget in tokens, for a figure no level gives. Send this or level, never both. | |
| occurredTo | No | The latest time the evidence may carry (ISO 8601), inclusive. | |
| occurredFrom | No | The earliest time the evidence may carry (ISO 8601), inclusive. | |
| queryTimestamp | No | Recall as of this moment (ISO 8601), with only what was known then. Now when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotent/destructive/openWorld, but the description adds genuinely non-structured context: it spends the project's credits where the plan prices a recall, and it requires project Read. It also notes results come 'each with its sources'. It does not detail pagination or result shape, keeping it just below the top.
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?
One dense paragraph, front-loaded with the core recall behavior before the scoping, cost and permission clauses. Every sentence contributes (parity, scoping, billing, permission), though the phrasing is slightly ornate and could be tightened.
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 10-parameter, no-output-schema tool, the description covers the important non-parameter facts an agent needs: mode selection, credit spend, and the project Read requirement. Return content is only briefly characterized ('each result with its sources'), which is acceptable given no output schema but leaves a small gap.
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 baseline is 3, but the description adds real semantic meaning beyond the schema: what identity scoping actually returns (whole project plus audiences that hold the identity) and that the tool matches the API's arguments, refusals and answer. That is useful interpretation the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Recalls from one project's memory') and pins it to the API operation POST /api/v1/recall, so an agent can distinguish it from siblings like ingest_memory or get_timeline. The two operating modes (with vs without identity) are spelled out, which further sharpens 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?
Clearly explains the two modes: with no identity it mirrors the console's Memories screen (everything in the project), with an identity it reads as that identity. It also states the prerequisite ('Needs project Read') and the cost behavior. It stops short of naming explicit alternatives among siblings (e.g., when to prefer get_timeline or find_trace_roots), so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes a member from the organization, or revokes a pending invitation. Mirrors Remove from organization and Revoke invitation on Settings › Members; needs Owner or Admin, removing an Owner needs an Owner, and the last Owner is refused. Their sessions end at once; keys they minted keep working. Destructive: call without confirm first, put the sentence it answers to the person, and pass confirm: true only if they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | True only once the person has agreed to the removal. | |
| memberId | Yes | The member's or invitation's id, as list_members returns it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial non-structured context: authorization tiers, the last-Owner refusal, immediate session termination, and the fact that keys the member minted keep working. That is exactly the side-effect detail an agent needs before a destructive call.
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 critical fact (what is removed, and that it is destructive) is front-loaded, and the later clauses each carry a distinct permission or side-effect detail. It is dense and semicolon-chained, which slightly hurts readability, but no sentence is 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?
With only two fully documented parameters, no output schema, and annotations covering the safety profile, the description closes every remaining gap: authorization, refusal conditions, post-removal effects, and the confirmation workflow. An agent has everything needed to invoke it correctly and safely.
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 baseline is 3, but the description adds real meaning by framing confirm as a two-step social gate (ask the person, then set confirm: true only on agreement) rather than a bare boolean. It also ties memberId to list_members output, reinforcing the schema note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Removes a member from the organization') and immediately extends the scope to the second case it covers ('or revokes a pending invitation'). This is enough for an agent to separate it from invite_member, resend_invitation, and revoke_project_grant 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?
Supplies concrete prerequisites (needs Owner or Admin, removing an Owner needs an Owner, last Owner is refused) and an explicit call protocol: call without confirm first, then pass confirm: true only if the person agrees. It does not name an alternative sibling tool for borderline cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renames a tag, as Manage tags does. The projects carrying it and the rules matching it follow the new name, so nobody's access moves. Renaming onto an existing tag is refused: merge_tags combines two tags. Owner and Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The tag's new name. | |
| tagId | Yes | The tag's id, exactly as list_tags returned it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the cascade behavior (projects carrying it and rules matching it follow the new name), the important safety fact that access does not move, the refusal-on-collision rule, and the permission requirement. The destructiveHint=true annotation is consistent with a rename that changes a global tag name, and the description supplies the operational context the annotations cannot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: action first, then behavioral consequence, then the exclusion and permission. Every sentence carries distinct, non-redundant information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only two fully described parameters, the description covers everything an agent needs: what changes, what does not, the failure condition, the alternative tool, and the authorization requirement. Nothing material is left unstated for this operation.
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 both parameters and their formats (including 'exactly as list_tags returned it') are already documented. The only added semantic is the constraint on `name` that it must not collide with an existing tag, which is useful but marginal against a fully documented 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 (rename) and resource (tag) and immediately positions it against the sibling merge_tags, which is the closest alternative. An agent can distinguish rename_tag from create_tag, delete_tag, and merge_tags without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the exclusion case (renaming onto an existing tag is refused) and routes to the correct alternative (merge_tags combines two tags), plus states the required role (Owner and Admin). It stops short of spelling out when to prefer renaming over delete/recreate, so it is clear context rather than a full when/when-not contract.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calls per time bucket over a range for one project, split by how they ended: accepted, accepted then failed later, and rejected. The bucket follows the range as on the screen, so a range never draws more than about a hundred buckets. Takes the same filters and search as list_requests. Mirrors the Requests screen's histogram; needs project Read on the project.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the range, ISO 8601. Defaults to now. | |
| from | No | Start of the range, ISO 8601. Defaults to 24 hours before `to`, the screen's default range. | |
| search | No | Matches a request id, a key name or a data point id. | |
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| keyNames | No | API key names to keep. | |
| statuses | No | Exact status codes to keep, for example [401]. | |
| endpoints | No | Endpoints to keep, as routed, for example "/api/v1/ingest". | |
| statusClasses | No | Status classes to keep: "2xx", "4xx", "5xx". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive. The description adds real context beyond them: the bucket-count cap ('never draws more than about a hundred buckets'), the meaning of the three outcome categories, and the required 'project Read' permission. Return format details are not given, keeping it just short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core behavior and free of filler; the bucket-cap and auth sentences both earn their place. Slightly dense in the opening sentence but well structured overall.
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 explains what the chart conveys (calls split by outcome per bucket) and the auth requirement, which is enough to invoke it correctly. It stops short of describing the exact response payload shape, a minor gap.
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 each of the 8 parameters is already documented with format, defaults, and examples. The description adds no per-parameter syntax or semantics beyond pointing at list_requests for the shared filter set, so the 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 and resource (calls per time bucket over a range) and immediately distinguishes itself from list_requests by describing aggregation and the accepted/late-failed/rejected split. An agent can tell this is a charting/aggregation tool rather than a row-listing tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Takes the same filters and search as list_requests' ties it to the sibling so the agent knows the filter surface is shared, and 'Mirrors the Requests screen's histogram' signals the visualization use case. No explicit when-not guidance, but the context is clear enough to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends a pending invitation again with a fresh link; the old link stops working. Mirrors Resend invitation on a pending row of Settings › Members; needs Owner or Admin. Where no mail goes out the answer carries the new link: give it to the person you act for and nowhere else.
| Name | Required | Description | Default |
|---|---|---|---|
| memberId | Yes | The invitation's id, as list_members returns it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing a destructive side effect ('the old link stops working'), the authorization requirement (Owner or Admin), and a security-sensitive response trait: when no mail is sent, the new link is returned and must not be shared beyond the person it is acted for. That last point is exactly the kind of context annotations cannot carry.
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 tightly packed clauses, front-loaded with the action and effect, then the UI/auth anchor, then the link-handling caveat. No filler text and nothing repeated from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly compensates by explaining the conditional return value (the new link when no mail goes out). Auth, destructive effect, and the distinction from creating an invitation are all covered, so an agent has everything needed to call it safely.
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 single parameter is fully documented in the schema ('The invitation's id, as list_members returns it'). The description adds no syntax, format, or sourcing detail beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('resend'), specific resource ('pending invitation'), and the concrete effect ('fresh link; the old link stops working'). It also anchors the tool by naming the UI equivalent ('Resend invitation on a pending row of Settings › Members'), which separates it cleanly from the create-oriented sibling invite_member.
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 context is clearly bounded to pending invitations and the caller requirement is stated ('needs Owner or Admin'). It does not explicitly name invite_member as the alternative for non-pending cases, so the when-not path is only implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs an ingestion that failed again, under the same ingestion id, as Retry in the request drawer and on Trace does. It spends no credits. Only a failed ingestion can be retried; explain_ingestion says whether a retry can fix it. Call it without confirm first, put the sentence it answers to the person, and pass confirm: true only if they agree. Needs project Write.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | ||
| project | No | The project's slug, exactly as get_viewer or list_projects returned it. May be omitted when the organization has one live project. | |
| ingestionId | Yes | The ingestion id, exactly as explain_ingestion or list_requests returned it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds context beyond them: 'spends no credits' and the authorization requirement 'Needs project Write'. It doesn't reconcile the destructiveHint=true flag with a seemingly non-destructive re-run, but the added cost/auth facts are genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and keeps to a tight set of sentences, each earning its place. Some phrasing is slightly awkward ('put the sentence it answers to the person'), which mildly hurts readability but not information density.
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, and the description still covers the essentials for a guarded mutation: cost, eligibility precondition, auth scope, and the confirm workflow that gates the call. It stops short of describing what the retried run returns or how the result is reported, but it is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%; project and ingestionId are documented in the schema, but confirm has no schema description. The description compensates by fully specifying confirm's semantics and gating flow ('Call it without confirm first... pass confirm: true only if they agree'), adding real meaning 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?
States a specific verb+resource ('Runs an ingestion that failed again, under the same ingestion id') and even maps it to the UI affordance the user knows ('as Retry in the request drawer and on Trace'). An agent can distinguish it from explain_ingestion and estimate_ingestion 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?
Gives explicit when-to-use ('Only a failed ingestion can be retried'), names the alternative that determines eligibility ('explain_ingestion says whether a retry can fix it'), and prescribes a two-step flow: call without confirm first, then pass confirm:true only on agreement. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Destructive: revokes a project key, which stops working on its next call and cannot be restored. id is the key id exactly as list_api_keys returned it. Without confirm: true nothing happens and the answer is the sentence to put to the person. Mirrors API keys › Delete; needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| confirm | Yes | ||
| project | No | The project's slug; omitted, the organization's only live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing that the key stops working on its next call (not instantly), that revocation is irreversible, and that confirm:false produces a no-op plus a human-facing prompt sentence. The Admin requirement and the UI equivalent are additional behavioral context the annotations do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tightly packed sentences, front-loaded with the 'Destructive:' warning, then the id format, the confirm gate, and the permission requirement. No filler; every clause carries operational 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?
With no output schema, the description still covers the return behavior for the confirm:false path, the irreversible mutation semantics, and the auth requirement. An agent has everything needed to call it correctly and safely.
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 only 33% (only `project` is documented), so the description must compensate — and it does, explaining that `id` must be the exact key id from list_api_keys and that `confirm: true` is what actually triggers the revocation. It still doesn't say what happens to the key's historical usage or whether the project param accepts a slug versus an id beyond the schema's own 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?
States a specific verb and resource (revokes a project key) and immediately scopes it with the consequence ('stops working on its next call and cannot be restored'). This clearly distinguishes it from siblings like delete_project, revoke_project_grant, or archive_project.
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 the prerequisite ('needs project Admin'), the mapping to the product UI ('Mirrors API keys › Delete'), and points at list_api_keys as the source for the id. It does not name an alternative tool or an explicit when-not-to-use case, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Withdraws one member's direct grant on a project at once; access they hold through their role or a rule stays. Mirrors the remove button on a grant in a project's Access tab; needs project Admin on that project. Destructive: call without confirm first, put the sentence it answers to the person, and pass confirm: true only if they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | The member's userId, as list_members or get_project_access returns it. | |
| confirm | Yes | True only once the person has agreed to the withdrawal. | |
| project | No | The project's slug; omitted, the organization's only live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds material context on top: that only the direct grant is withdrawn while role/rule access survives, the Admin permission requirement, and the human-confirmation workflow. This is exactly the additional behavioral detail the annotations cannot express.
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 front-loaded and purposeful: scope, human-facing analogy plus permission, then the destructive-call protocol. No filler and the most important constraint lands first.
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 destructive, boolean-gated mutation with no output schema, the description covers purpose, side effects, prerequisites, and the confirmation protocol. An agent has everything needed to invoke it safely and 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 all three parameters (including project's nullable default and userId's source) are already documented. The description restates the confirm semantics rather than adding new parameter meaning, so the 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+resource ('Withdraws one member's direct grant on a project') and immediately bounds the scope: role- and rule-derived access 'stays'. This distinguishes it from grant_project_access (the inverse), remove_member, and delete_access_rule without needing the schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the selecting condition clearly via the 'Mirrors the remove button on a grant in a project's Access tab' analogy, states the prerequisite ('needs project Admin on that project'), and spells out a two-step protocol (call without confirm, then pass confirm: true only on agreement). It stops short of naming a sibling tool as the alternative for other access-removal cases, so it is clear context rather than explicit when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes a member's platform role: Owner, Admin, Member or Billing. Mirrors the Platform role select on Settings › Members; needs Owner or Admin, and only an Owner sets or clears Owner. Making someone Owner transfers ownership: they become the Owner and the person you act for becomes an Admin. A pending invitation cannot become Owner, and the last Owner cannot step down. Destructive: call without confirm first, put the sentence it answers to the person, and pass confirm: true only if they agree.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | Owner, Admin, Member or Billing. | |
| confirm | Yes | True only once the person has agreed to the change. | |
| memberId | Yes | The member's id, as list_members returns it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds the annotations: it discloses the ownership-transfer side effect (actor is demoted to Admin), the pending-invite restriction, the last-Owner guard, and an explicit destructive-confirmation protocol tied to the confirm parameter. This is precisely the behavioral context the destructiveHint/idempotentHint flags cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb, resource and role set, then escalates to permissions, side effects and the destructive protocol. Dense but every sentence carries a constraint; the role enumeration is mildly redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param mutation with no output schema, the description covers prerequisites, ownership side effects, blocked cases and the confirmation workflow. An agent has everything needed to call it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for 'confirm' by specifying the two-step flow: call without confirm to obtain the sentence, then pass confirm: true only after the person agrees. The role list merely echoes 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 ('Changes') and resource ('a member's platform role'), and enumerates the four possible roles. The word 'platform' plus the Settings › Members reference distinguishes it from project-scoped siblings like grant_project_access and from invite_member/remove_member.
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 clear context: it mirrors the Platform role select on Settings › Members and requires Owner or Admin, with Owner-only for setting/clearing Owner. It states exclusions (pending invitation cannot become Owner; last Owner cannot step down). It stops short of explicitly naming the sibling to use for project-level access instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets a project's monthly caps, as Set caps on Settings › Projects does: ingestions a month and credits a month. Both are set together, so a cap you omit is cleared; pass the one to keep as well. Needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. | |
| creditCap | No | Credits a month, at least 1 — what the project's writes may spend; recall is never capped. Omit it for no credit cap. | |
| ingestionCap | No | Ingestions a month, at least 1. Omit it for no ingestion cap. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true; the description adds the specific mechanics of that destruction (an omitted cap is cleared, so anything not passed is wiped) plus the auth requirement (project Admin). This is meaningful context beyond the bare hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then the destructive interaction rule, then the permission requirement. No filler; 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 3-param mutation tool with no output schema, the description covers purpose, replace semantics, and auth needs, and the schema fully documents each parameter. The only minor gap is no mention of the failure mode (e.g. what happens if the slug is wrong).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds the set-together/omit-clears interaction that governs how all three parameters behave collectively — semantics the per-property schema text does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: it sets a project's monthly ingestion and credit caps, and names both cap types explicitly. No sibling tool (update_project, admin_grant_credits) does this, so an agent can identify it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the crucial replace semantics — 'Both are set together, so a cap you omit is cleared; pass the one to keep as well' — which tells the agent how to call it safely. It also states the Admin prerequisite. It stops short of naming when to prefer another tool, but no obvious alternative exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Brings an archived project back, as Unarchive on Settings › Projects does: in the switcher and taking calls on its keys again. Needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds real behavioral value beyond that: the authorization requirement (project Admin) and the observable effects on the project switcher and ingest keys.
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?
One tight sentence that front-loads the action and its effect, then the prerequisite. No filler and nothing buried.
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-optional-parameter, non-destructive, idempotent mutation with no output schema, the description covers the action, its effect, and the auth requirement. Nothing an agent needs in order to invoke it 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 single parameter's semantics (slug format, when it may be omitted) live entirely in the schema. The description adds no parameter detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (unarchive a project) and describes the concrete effect: it returns to the switcher and its keys take calls again. This clearly separates it from the sibling archive_project.
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 names the prerequisite ('Needs project Admin') and anchors the action to the equivalent UI control, giving clear context for when to use it. It stops short of naming archive_project as the inverse or stating any when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renames a group or sets its members. What you omit is kept; userIds, when sent, is the whole membership. Mirrors editing a group on Settings › Roles & access; needs Owner or Admin. Everyone is built in and cannot be renamed or emptied.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The new name; omitted, the name stays. | |
| groupId | Yes | The group's id, as list_access_groups returns it. | |
| userIds | No | Every member the group should hold, by userId; omitted, the members stay. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety flags (destructiveHint, idempotentHint), but the description adds meaningful behavior beyond them: the patch semantics of omitted fields, the replacement (not additive) nature of userIds, required role, and the immutable built-in group. These are exactly the traits an agent needs before mutating membership.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the action, then partial-update semantics, then the destructive-replacement caveat, then prerequisites and the immutable exception. No sentence is wasted.
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 covers the critical concerns: side effects (membership replacement), partial-update behavior, auth requirements, and the edge case of the built-in group. Nothing essential to calling it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: 'userIds, when sent, is the whole membership' clarifies replace-not-append behavior, and 'what you omit is kept' frames name/groupId as optional patches. This meaningfully extends the schema docs.
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 specific verbs and resource: 'Renames a group or sets its members.' This clearly separates it from siblings like create_access_group, delete_access_group, and list_access_groups. An agent can tell what the tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear operational context: partial-update semantics ('What you omit is kept'), prerequisites ('needs Owner or Admin'), and an exclusion ('Everyone is built in and cannot be renamed or emptied'). It does not explicitly name alternatives (e.g., delete_access_group for removal), so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces a rule with what you send, as saving the rule drawer does: send every group, person and tag it should keep. Mirrors editing a rule on Settings › Roles & access; needs Owner or Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | The tags to match; required unless match is Every. | |
| level | Yes | Read, Write or Admin. | |
| match | Yes | All (the project carries every tag), Any (at least one), or Every (every live project, whatever it carries). | |
| ruleId | Yes | The rule's id, as list_access_rules returns it. | |
| userIds | No | People by userId, as list_members returns it. | |
| groupIds | No | Group ids, as list_access_groups returns them. | |
| expiresAt | No | When the rule lapses, as an ISO 8601 date or time in the future; omitted, it never does. A date already past is refused. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further by explaining *how* it destroys (anything omitted is dropped) and adds an authorization requirement (Owner or Admin) that no annotation carries. It does not mention rate limits or the refusal of past expiresAt dates, which the schema covers instead.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the critical replace-in-full constraint front-loaded right after the verb. The UI metaphor and auth requirement are compressed into a single trailing clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter destructive mutation with no output schema, the description covers the two things an agent would otherwise get wrong: that this is a total replacement and that it requires elevated permissions. Return behavior is not described, but callers mainly need to avoid silently dropping grants, which is addressed.
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; the description adds meaning by clarifying that tags, userIds and groupIds are a complete replacement set, not an additive patch. It adds nothing for level, match, ruleId or expiresAt beyond what the schema already says.
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 ('Replaces a rule') and immediately clarifies the full-replacement semantics rather than a patch, which separates it from create_access_rule. The UI analogue ('as saving the rule drawer does') pins the mental model without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context ('Mirrors editing a rule on Settings › Roles & access; needs Owner or Admin') and the operational precondition that every group/person/tag to keep must be sent. It stops short of naming siblings such as preview_access_rule as the pre-flight alternative, so no explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renames a project and sets its tags, as the Settings › Projects drawer does. The slug never changes. Tags must already exist (list_tags); applying or removing one can change who reaches the project. Needs project Admin.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The new display name. Omit it to keep the name. | |
| tags | No | Every tag the project should carry, replacing the tags it has. Omit it to keep them. | |
| project | No | The project's slug, exactly as list_projects returned it. Omit it only when the organization has one live project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower, yet the description adds non-obvious behavioral context: the slug is immutable, tags must pre-exist, applying or removing a tag 'can change who reaches the project' (an access-control side effect), and Admin rights are required. These are exactly the hidden consequences an agent needs and that annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core action, then constraints. Every sentence carries distinct information (scope, slug invariance, tag prerequisite, permission) with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description could say more about the result of the update, but it is otherwise complete for a 3-param mutation: it covers purpose, prerequisites, auth, and side effects. Return/failure behavior is the only notable omission.
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 baseline is 3; the description nonetheless adds meaning beyond the schema by stating that the slug never changes and that tags must already exist, both of which govern how 'name' and 'tags' should be supplied. The information is real but thin, so it sits modestly above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: renaming a project and setting its tags, anchored to the familiar Settings › Projects drawer. It also preempts a common confusion with 'the slug never changes', which separates it from rename-style siblings. It falls just short of 5 because it never names a contrasting sibling tool directly.
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 real operational context: tags must already exist and points the agent at list_tags to obtain them, plus the 'Needs project Admin' prerequisite. It does not, however, say when to prefer this over adjacent tools like set_project_caps, archive_project, or rename_tag, so it stops short of explicit alternatives.
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.
admin_create_signup_campaignadmin_end_signup_campaignadmin_find_organizationadmin_get_contractadmin_get_organizationadmin_grant_creditsadmin_invoice_creditsadmin_list_signup_campaignsadmin_quote_creditsadmin_set_contractadmin_start_free_flexadmin_sync_subscriptionadmin_update_signup_campaignarchive_project1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]create_access_group2 fields changedInput schema / properties / userIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / userIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]create_access_rule7 fields changedInput schema / properties / expiresAt / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / groupIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / groupIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / tags / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / tags / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / userIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / userIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]create_api_key1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]create_mcp_access_link4 fields changedInput schema / properties / expiresAt / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / traits / additionalProperties / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / traits / typePrevious value: -"object"New value: +[
+ "object",
+ "null"
+]delete_project1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]enable_mcp_server1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]estimate_ingestion3 fields changedInput schema / properties / points / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / timeZone / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]explain_ingestion2 fields changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / requestId / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]find_trace_roots4 fields changedInput schema / properties / afterMemories / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / afterSources / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / search / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_credit_balance1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_lineage3 fields changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / reveal / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / reveal / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]get_mcp_server1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_project1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_project_access1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_request1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_timeline1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]get_trace_node1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]grant_project_access2 fields changedInput schema / properties / expiresAt / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]ingest_memory5 fields changedInput schema / properties / audience / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / id / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / identity / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / label / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]list_api_keys1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]list_requests10 fields changedInput schema / properties / after / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / endpoints / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / endpoints / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / keyNames / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / keyNames / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / search / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / statusClasses / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / statusClasses / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / statuses / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]preview_access_rule6 fields changedInput schema / properties / groupIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / groupIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / tags / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / tags / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / userIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / userIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]recall_memory4 fields changedInput schema / properties / identity / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / level / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / sort / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]request_histogram9 fields changedInput schema / properties / endpoints / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / endpoints / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / keyNames / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / keyNames / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / search / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / statusClasses / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / statusClasses / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / statuses / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]retry_ingestion1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]revoke_api_key1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]revoke_project_grant1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]set_project_caps1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]unarchive_project1 field changedInput schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]update_access_group3 fields changedInput schema / properties / name / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / userIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / userIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]update_access_rule7 fields changedInput schema / properties / expiresAt / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / groupIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / groupIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / tags / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / tags / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]Input schema / properties / userIds / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / userIds / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]update_project4 fields changedInput schema / properties / name / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / project / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / tags / items / typePrevious value: -"string"New value: +[
+ "string",
+ "null"
+]Input schema / properties / tags / typePrevious value: -"array"New value: +[
+ "array",
+ "null"
+]ingest_memoryrecall_memoryarchive_projectcreate_access_groupcreate_access_rulecreate_api_keycreate_mcp_access_linkcreate_projectcreate_tagdelete_access_groupdelete_access_ruledelete_projectdelete_tagenable_mcp_serverestimate_ingestionexplain_ingestionfind_trace_rootsget_credit_balanceget_lineageget_management_key_activityget_mcp_serverget_organizationget_planget_projectget_project_accessget_requestget_timelineget_trace_nodeget_usageget_viewergrant_project_accessinvite_memberlist_access_groupslist_access_ruleslist_api_keyslist_memberslist_projectslist_requestslist_tagsmerge_tagspreview_access_ruleremove_memberrename_tagrequest_histogramresend_invitationretry_ingestionrevoke_api_keyrevoke_project_grantset_member_roleset_project_capsunarchive_projectupdate_access_groupupdate_access_ruleupdate_projectDurable, versioned memory for AI assistants. Remote memory needs a Pastepile subscription.
Long-term memory for AI agents. Pass one sentence, and it remembers, recalls, or forgets.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Private memory for AI agents: save and recall facts across Claude Code, Codex, Cursor and ChatGPT.
Add one secure layer between your agents and this server.
