Parabol MCP by usefulapi

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

With only destructiveHint available in annotations, the description carries most of the burden and delivers: it names the required permission (COMMENTS_WRITE), the underlying GraphQL mutation and its union return type, and the mutation nature of the call. It does not explain reversibility or the union member semantics, keeping it just short of the top score.

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 critical 'MUTATES' warning and required-parameter list, and is dense without padding. Slightly terse packing of permission and GraphQL details into one line, 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 mutation with no output schema, the description supplies permission requirements, the operation name, and the return type, plus required/optional parameter roles. Return-value structure is only gestured at ('→ union') rather than described, leaving 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 coverage is 100%, so baseline is 3; the description adds some meaning ('stringified TipTap/ProseMirror JSON document', threadParentId used 'to reply'). However it mislabels threadSortOrder as Required when the schema marks only content and discussionId as required, a discrepancy that could push agents to always supply 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?

States a specific verb and resource ('add a comment to a meeting discussion thread') and immediately flags the write nature of the operation. No sibling tool performs comment creation, and the meeting-thread scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clarifies the reply case ('threadParentId (to reply)') and the reply-vs-new-comment distinction, which is useful implied usage. However, it gives no explicit when-to-use/when-not guidance or alternatives, so this is 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.

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

Annotations only supply destructiveHint=true, so the description carries real weight: it declares the mutation, the required MEETINGS_WRITE scope, the backing GraphQL call, and the <=2000-char TipTap/ProseMirror format constraint. Auth and format disclosures go well beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the mutation warning, then the required/optional fields and GraphQL backing in a tight paragraph. No wasted sentences, though the required-field enumeration is dense and includes the inaccurate sortOrder claim.

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 with no output schema, the description covers the operation, required inputs, content format, and permission scope adequately. The mislabeled required sortOrder is the main gap; return behavior is reasonably out of scope without an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description largely restates schema details (float sortOrder, stringified TipTap content). It also states sortOrder is Required, contradicting the schema where it is optional with a default of 0, which slightly undermines the parameter guidance.

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 ('add a reflection card') plus its scope ('a running retrospective's reflect phase'), which cleanly separates it from mutation siblings like add_comment and create_task. The leading 'MUTATES Parabol data' immediately signals the operation class.

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 for use: it targets a retrospective that is running and in its reflect phase, and notes the MEETINGS_WRITE requirement. It does not name alternatives (e.g. add_comment) or state when-not-to-use, 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.

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

With only destructiveHint=true in annotations, the description adds real behavioral value: it declares this is a mutation, names the exact GraphQL operation, discloses the required write scope (TASKS_WRITE), and warns that `content` must be a stringified TipTap/ProseMirror document. It omits return shape, idempotency, and how `fields` interacts with the typed fields.

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 mutation warning and required inputs, then moves to optional links and the permission requirement. Dense but every sentence contributes; the GraphQL signature line is slightly redundant with the schema but useful for agents familiar with Parabol.

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 mutation with a nested free-form `fields` object and no output schema, it covers required fields, optional relationships, content format, and auth scope. The gap is the verbatim-merge escape hatch in `fields`, which is undeclared in the description.

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 flagging which params are required, spelling out the status enum, and explaining the plaintextContent-vs-content distinction. It still doesn't explain the `fields` override or `sortOrder`.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with an explicit verb+resource+scope: 'MUTATES Parabol data: create a task on a team', and names the underlying mutation createTask(newTask, area). An agent can distinguish it from update_task and list_tasks 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 states the required inputs (teamId, status with its enum values) and gives positive guidance on the content fields (use plaintextContent for text, and/or content as stringified TipTap/ProseMirror JSON). It also names the TASKS_WRITE prerequisite. It does not explicitly contrast with update_task or add_comment, so it stops short of full when/when-not routing.

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

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

Beyond the readOnlyHint annotation, the description discloses the return composition (phases, stages, reflection groups, reflections, vote/topic/task/comment counts), the __typename discriminator for meeting types, the underlying GraphQL call viewer.meeting(meetingId), and the required MEETINGS_READ permission. For a read tool with no output schema, this is substantial added 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?

Three front-loaded sentences: purpose, then type-conditional return detail, then implementation/permission notes. Every sentence contributes information, though the GraphQL mapping sentence is denser implementation detail than an agent strictly needs. Appropriately sized 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 carries the burden of describing return values and does so well, including the retrospective-specific extras and the __typename discriminator. The permission requirement and single required param are covered, leaving little an agent would need before calling 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?

There is a single required parameter, meetingId, documented in the schema at 100% coverage. The description does not add format, source, or acquisition guidance (e.g. where to obtain a meetingId), so it does not exceed the schema baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Fetch one meeting by id with its phases and stages.' The singular 'one meeting by id' clearly separates it from list_meetings/list_active_meetings siblings, and it further clarifies what a retrospective returns. An agent can identify the tool's exact scope 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?

Usage is implied by 'Fetch one meeting by id' plus the note about retrospective-specific payloads, which hints at when the extra fields appear. However, it never explicitly names alternatives (list_meetings, list_active_meetings) or states when not to use it. 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.

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

Annotations only cover the safety profile (readOnlyHint=true), so the description carries most of the behavioral burden. It usefully discloses the required scopes (ORGS_READ, plus TEAMS_READ for teams) and the fact that team data is expanded into the response. It does not, however, say what happens if the caller lacks TEAMS_READ or if the org id is unknown.

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 short sentences, front-loaded with the action and resource, followed by the implementation reference and permission needs. No filler; every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with no output schema, the description covers the essentials: what is returned (organization plus teams) and what authorization is needed. It is only slightly light on error/edge-case behavior and alternative listing tools.

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 orgId parameter, so the schema already documents it. The description adds only marginal meaning (that the id selects one organization and that teams are included), which is the expected baseline 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 and resource ('Fetch one organization by id') and adds scope detail ('including its teams'). The singular 'one ... by id' implicitly distinguishes it from the sibling list_organizations, but it never names that sibling, so the differentiation is left to inference.

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 by 'by id' (lookup of a known organization) rather than stated. There is no explicit when-to-use vs when-not, and no alternative (e.g. list_organizations for browsing) is named. The permission requirements are the only routing-relevant context.

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

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

Annotations only supply readOnlyHint, so the description carries the rest and does: per-field authorization (TEAMS_READ, plus MEETINGS_READ for activeMeetings and ORGS_READ for organization) tells the agent exactly what the call will fail without, and the return enumeration discloses that this is an aggregated, multi-entity read. That is substantive context beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the return payload, then the resolver mapping, then permissions — no filler. The GraphQL resolver line is denser than prose but earns its place given the parabol_graphql/parabol_query siblings.

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 compensating by enumerating the returned entities is exactly what an agent needs. With the single required param documented at 100% and permissions spelled out, nothing material is missing for a one-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?

Schema description coverage is 100% and the single teamId parameter is fully documented there, so the baseline is 3. The description only restates 'by id' and adds no format or sourcing detail (e.g., where to obtain the id) 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?

Specific verb+resource ('Fetch one team by id') with an explicit enumeration of what is returned (metadata, members with their user, active meetings, organization). The singular 'one team' cleanly separates it from list_teams and the surrounding get_* siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'one team by id' scoping makes the usage condition clear relative to list_teams/list_team_members, and it names the underlying resolver for parity with parabol_graphql. It stops short of an explicit when-not or a named alternative for the meeting/org sub-resources it inlines (get_meeting, get_organization).

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value beyond that by disclosing the required USERS_READ scope and naming the returned fields. It does not mention rate limits or auth failure behavior, but for a simple read 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?

Front-loaded with the purpose in the first clause, and the return fields plus scope come next. The inline 'Parabol GraphQL: query { viewer { ... } }' snippet is mildly redundant given the sibling parabol_query tool, but it clarifies the backing operation rather than wasting 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?

No output schema exists, and the description compensates by enumerating the returned fields (id, preferredName, email, tier, tms). For a zero-parameter read tool this is nearly complete; only the exact shape of 'tms' (team id array vs objects) is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no input is needed (it queries the token owner), and the schema has nothing to document.

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 ('Fetch the authenticated Parabol user (the token owner)') and pins the scope with 'the token owner,' which cleanly separates it from sibling tools like list_organization_users or get_team. 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 explicit when-to-use guidance: 'Start here to discover your identity and team ids.' That is a clear routing signal, but it names no alternatives or exclusions (e.g., when to prefer list_team_members for members other than yourself), so it stops short of the 5 bar.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the behavioral load and does so well: it declares the mutation nature, the authorization requirement (TEAMS_WRITE), and the outward-facing side effect that emails are actually sent. It stops short of covering failure/duplicate-invite behavior or rate 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?

Three compact sentences, mutation warning front-loaded, followed by requirements and permission. Every clause carries information and nothing is 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?

For a 3-parameter mutation with no output schema, the description covers purpose, required inputs, scoping, and the permission gate. Only return/error semantics and duplicate-invite behavior are unaddressed, which is 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 all three parameters are already documented in the schema. The description only restates which are required and which is optional, adding no format, validation, or edge-case detail beyond the schema — the baseline 3 for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('send team invitations by email') and explicitly flags it as a mutation of Parabol data. It also gives the underlying GraphQL mutation signature, so an agent can distinguish it immediately from read-oriented siblings like list_team_members or get_team.

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 the required parameters, the optional meetingId scoping, and the required TEAMS_WRITE permission, which is clear usage context. It does not name an alternative tool or a when-not-to-use condition, but no sibling competes for this operation.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real value beyond that by stating the required authorization scopes and the resolver path behind the call. It does not describe pagination or ordering of the returned list, which keeps it 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?

Two compact sentences: the purpose and scope come first, then the backing resolver and required scopes. No filler and nothing redundant with the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only list tool with no output schema, the definition covers purpose, scope, and authorization adequately. Minor gaps remain around return shape (empty list vs error) and ordering, but annotations cover the safety burden.

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 teamId parameter, so the schema already carries the meaning. The description adds no extra syntax, format, or sourcing detail about the id, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('List'), resource ('meetings'), and an explicit scope qualifier ('currently-active (in-progress)') that separates it from the sibling list_meetings. It even names the underlying GraphQL resolver path, so an agent knows exactly what is being fetched.

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 by the scope ('active/in-progress'), and the required scopes (TEAMS_READ + MEETINGS_READ) are a genuine prerequisite signal. However, it never explicitly says when to prefer this over list_meetings or get_meeting, nor any exclusion.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: newest-first ordering, cursor direction semantics for before/after, default page behavior, and the MEETINGS_READ 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?

Four dense, front-loaded sentences; the required-parameter fact comes early and every clause carries information (scope, ordering, defaults, pagination, auth). No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with no output schema, the description supplies everything needed to call it correctly: required arg, defaults, pagination direction, ordering, and permission requirement. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description nevertheless adds value by framing before/after as an upper-bound/cursor pair that walks the window backwards and by confirming teamIds is required and meetingTypes defaults to all four — adding relational meaning over isolated field 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 a specific verb+resource ('List past/ongoing meetings') with scope ('for one or more teams'), ordering ('newest first'), and backing API (viewer.meetings). The 'past/ongoing' framing distinguishes it from the sibling list_active_meetings and from get_meeting, so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: teamIds is required, meetingTypes defaults to all four, before defaults to now, and after paginates older. It stops short of explicitly naming when to prefer list_active_meetings or get_meeting, so no explicit alternatives/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, yet the description adds real value beyond them: the required ORGS_READ permission and the returned fields (id, name, tier, billingTier). No pagination or ordering behavior is disclosed, but for a viewer-scoped org list 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?

Three compact, front-loaded fragments with no filler — scope first, then return shape, then the GraphQL path and permission. The GraphQL path is implementation detail but useful routing for the parabol_query sibling, 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, listing the returned fields is the right compensating move, and the auth requirement is stated. For a zero-parameter read list, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify and nothing misleading about 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?

States a specific verb (List) and resource (organizations) with an explicit scope ('the viewer belongs to') and enumerates returned fields. It implicitly distinguishes itself from the singular get_organization sibling via that scope, but never names an alternative 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?

Usage is implied by the scope ('the organizations the viewer belongs to') and the auth gate, but there is no explicit when-to-use or when-not-to-use guidance relative to get_organization, get_viewer, or list_organization_users.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds the required scopes (ORGS_READ + USERS_READ), the Relay connection semantics, and the pagination contract via `first`/`after`. It stops short of describing failure modes or rate limits, but the added auth and shape context is substantive.

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 paragraph that front-loads the resource and scope before moving to pagination and permissions; every clause carries information. Slightly compressed but no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating return fields (role, joinedAt, tier, user preferredName/email) and spelling out pagination and permissions. Only error behavior and page-size limits go unmentioned, which are minor here.

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 orgId, first, and after are already documented in the schema, including the 'cursor of the last edge' wording. The description's pagination note largely restates that, so it earns only 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 the users in an organization'), and further pins the scope with the Relay connection and GraphQL path, plus the exact fields returned. An agent can distinguish this from list_team_members or list_organizations without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear calling context (Relay pagination, required scopes ORGS_READ + USERS_READ) but never states when to prefer this over siblings such as list_team_members, nor any exclusion conditions. Usage is implied by the resource named rather than explicitly guided.

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

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

Annotations only supply readOnlyHint=true; the description adds genuinely new behavioral context by disclosing the required scope (TASKS_READ), the Relay connection shape, and the cursor-based pagination contract. It stops short of describing ordering or what happens when filters combine, but it clears the lower bar set 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, zero filler, and the scoping statement is front-loaded ahead of filtering and pagination mechanics. Each sentence carries independent 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 an 8-parameter read tool with no output schema, the definition covers scope, filters, pagination, and auth. The one real gap is return shape, but the mention of a 'Relay connection' gives the agent enough to expect edges/nodes/pageInfo.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter (including the after cursor, page-size bounds, and status enum) is already documented in the schema. The description only paraphrases the filter set at a high level and adds no syntax or default details beyond it, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the viewer's tasks') and names the underlying GraphQL field (viewer.tasks), which lets an agent distinguish it from create_task and update_task without opening any schema. The explicit 'viewer's' scope also prevents confusion with team-wide listing tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description enumerates the available filters and explains pagination, which implies the usage context, but it never says when to prefer this tool over the generic parabol_query / parabol_graphql siblings that could also fetch tasks. No exclusions or alternative routing are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the required permission scope (TEAMS_READ) and the exact set of returned attributes, which matters since there is no output schema. It omits pagination or ordering behavior, keeping it 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?

A single front-loaded sentence plus a GraphQL path and a permission note; every clause carries information and nothing is wasted. Slightly dense but well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only two-parameter list tool with full schema coverage and a safety annotation, the definition covers permission requirements and return shape. The absence of an output schema is compensated by the enumerated fields; only missing piece is pagination/ordering context.

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 both parameters (teamId, sortBy) are already documented in the schema. The description echoes teamId via the GraphQL path but adds no syntax or format detail (e.g. valid sortBy values) 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 ('List') and resource ('members of a team') and enumerates the returned fields (isLead, isOrgAdmin, preferredName, email), so the agent knows exactly what is produced. It does not explicitly differentiate from the similarly named sibling list_organization_users, but the team-scoped resource is clear enough to distinguish them.

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 by 'List the members of a team' and a prerequisite ('Requires TEAMS_READ') is given, but there is no explicit when-to-use versus alternatives such as get_team or list_organization_users. The agent must infer the routing from the resource name alone.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is the required TEAMS_READ scope and the underlying GraphQL field (viewer.teams). Archived teams are excluded by default, which the schema covers. It adds real auth/implementation context beyond annotations, though it stops short of describing result size or ordering 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?

Two tight sentences with the purpose and scope front-loaded before the auth prerequisite. The 'Parabol GraphQL: viewer.teams' fragment is mildly redundant implementation detail but plausibly aids agents mapping to the query layer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool, the description covers purpose, returned fields (needed since there is no output schema), and the auth scope. It omits any mention of pagination or result limits, which is the only meaningful gap given the annotations already cover safety.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter has 100% schema description coverage including its default (false), so the schema carries the semantics. The description never mentions includeArchived or its effect, which is the baseline-3 outcome when structured data already does the work.

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 (teams), scopes it precisely to 'the teams the viewer belongs to', and enumerates the returned fields (id, name, orgId, tier, team lead). This distinguishes it from siblings like get_team (single team) and list_organization_users without needing to open 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 implied by the 'viewer belongs to' scope and the stated TEAMS_READ prerequisite, which is useful auth guidance. However, there is no explicit when-to-use vs alternatives (e.g., get_team or list_organizations) and no stated exclusions or pagination expectations.

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

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

With destructiveHint=true already declared, the description still adds real value by warning that the call can mutate data, that the endpoint is action.parabol.co/graphql, that the token must carry the required scope, and that arbitrary operations are permitted. It stops short of describing failure behavior or rate limits, but the auth/scope disclosure and mutation warning go meaningfully beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The highest-stakes information (potential mutation) is front-loaded in the first clause, followed by purpose, then the routing hint. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a passthrough GraphQL escape hatch with no output schema, the description covers purpose, alternatives, endpoint, and auth requirements. It could say more about how errors or GraphQL-level failures are surfaced, but nothing essential to invoking 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% and both parameters are documented in the schema, so the baseline is 3. The description only adds that variables are optional and that the query may be a mutation document — a marginal clarification rather than new syntax or format detail.

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 concrete verb and resource — run an arbitrary GraphQL operation (query or mutation) against action.parabol.co/graphql — and explicitly positions itself as an escape hatch for operations the curated tools don't cover. An agent can immediately separate it from siblings like parabol_query or update_task 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 states when to use it (operations not covered by curated tools), when not to (read-only calls) and names the alternative explicitly: "Prefer parabol_query for read-only calls." That is a complete routing rule with a named sibling, 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.

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

Annotations declare readOnlyHint=true, and the description goes beyond that with a real behavioral constraint (mutations rejected), an auth requirement ('matching read scope(s) on your token'), and the target endpoint. It does not mention rate limits, query depth/complexity limits, or the response shape, so it stops short of the top score.

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 escape-hatch framing and tightly written; four sentences each carry information (scope, endpoint, rejection rule, family routing, auth). Slightly dense but no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generic GraphQL passthrough with no output schema, the description covers purpose, restrictions, and auth scope adequately; the agent already knows a GraphQL response shape. Minor gap: no mention of complexity/pagination limits for arbitrary queries.

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% with only two parameters, so the schema already documents 'query' and 'variables' fully. The description adds marginal value by noting variables are optional, but supplies no format or syntax guidance beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('run an arbitrary Parabol GraphQL QUERY') plus the exact endpoint, and explicitly distinguishes itself from siblings: it is the read-only escape hatch while 'parabol_graphql' and the dedicated write tools handle mutations. An agent can route correctly 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 both when-to-use ('for fields not covered by the curated read tools') and when-not ('Mutations are REJECTED'), and names the alternative tools to use in the rejected case. This is explicit routing guidance, not inference.

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

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

Annotations only supply destructiveHint=true; the description adds real value by flagging 'MUTATES Parabol data', naming the auth scope (MEETINGS_WRITE) and the underlying GraphQL operation (startCheckIn → union). It stops short of describing side effects such as notifying team members or whether concurrent meetings are allowed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but waste-free: mutation/advisory flag first, then required param, then optional param, then permission. 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-parameter mutation with no output schema, the description covers the mutation risk, required auth scope, and the returned meetingId. Only the side-effect/visibility story is absent, which is 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 coverage is 100%, so both parameters are already documented, and the description merely restates 'Required: teamId. Optionally name it.' No format, ID source, or naming guidance is added beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource pair ('start a new Check-in (Action) meeting for a team') and even discloses the return value (meetingId). It is clearly distinguishable from siblings like start_retrospective and start_team_prompt by the meeting type.

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: required teamId, optional name, and the MEETINGS_WRITE permission requirement. It does not explicitly say when to prefer this over the sibling meeting starters, but the meeting-type framing makes the selection context clear.

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

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

Annotations supply only destructiveHint and a title, so the description carries real weight: it declares the write nature ("MUTATES"), the required permission scope (MEETINGS_WRITE), the returned value (meetingId), and the underlying GraphQL operation with a union return. It does not cover idempotency or what happens when the team already has an active retro, keeping it 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?

A single dense block with the mutation warning front-loaded, followed by required/optional params, then auth scope and backend mapping. Every clause adds information and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation with no output schema, the description covers the essentials: mutation semantics, permission requirement, and the return value shape. It stops short of documenting the union/error cases or behavior when a meeting is already running.

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 both parameters are already documented in the schema. The description merely restates that teamId is required and name is optional, adding no format, constraint, or default information beyond structured data.

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 (start a retrospective meeting) plus its scope (for a team), which cleanly separates it from the sibling start tools start_checkin and start_team_prompt. It also flags the mutation up front, so the operation type 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?

The description states prerequisites (required teamId, optional name, MEETINGS_WRITE scope) but never says when to pick this over alternatives such as start_checkin/start_team_prompt or how it relates to list_active_meetings. Usage is only implied by the resource name.

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

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

Goes beyond annotations by disclosing the required MEETINGS_WRITE permission and the underlying GraphQL mutation (startTeamPrompt) returning a union type. It also flags the operation as a data mutation up front. It does not explain what happens to an existing active meeting or whether the call is idempotent, which is a minor gap given destructiveHint=true is already declared.

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 compact sentences, each carrying distinct information (mutation flag, purpose, parameter requirements/defaults, GraphQL/auth context), with the mutating nature front-loaded. No redundant phrasing.

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 mutation with no output schema, the description covers the essentials: what it creates, required vs optional inputs, the default, the permission required, and the return shape (union). It stops short of explaining side effects on existing meetings or error conditions, but is otherwise sufficient to 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%, so both parameters are already documented in the schema. The description restates teamId as required and name's default of 'Standup' but adds no format, ID source, or constraint information beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (start) and resource (a new async Standup / Team Prompt meeting for a team), and distinguishes itself from the sibling start_checkin and start_retrospective tools. An agent can identify exactly which meeting type this creates 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?

The description implies usage context (starting a standup for a given team) but never states when to prefer this over start_checkin or start_retrospective, nor any preconditions such as team membership. Usage is inferable from the purpose but not explicitly guided.

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

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

Adds real behavioral context beyond the destructiveHint annotation: the auth requirement ('Requires TASKS_WRITE'), the partial-update semantics, and the underlying GraphQL mutation shape updateTask(updatedTask, area). It does not describe reversibility or the response, but it is consistent with the annotations and usefully supplements them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the mutating classification, then required vs optional fields, then the auth requirement. Four dense sentences, each carrying 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?

For a partial-update mutation with no output schema, the description covers the required param, the mutation semantics, and the permission scope an agent needs before calling. Return value behavior is not covered, but the critical invocation details are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents id, area, status, userId, content, sortOrder, and fields. The description restates format hints (stringified TipTap JSON, userId reassignment) and the mutation signature, adding some value, but the undocumented 'fields' escape hatch is only explained in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('update an existing task'), identifies the required id, and enumerates the mutable fields. The mutating nature and scope make it trivially distinguishable from create_task, list_tasks, and the read 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 usage context via 'Only included fields change,' which tells the agent this is a partial update and that unspecified fields are untouched. It does not name alternatives or when-not-to-use conditions, but the operation is unambiguous enough that this is a minor gap.

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