parabol

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

Says upfront that it mutates data and requires COMMENTS_WRITE, adding useful permission and side-effect context beyond the destructiveHint annotation. The mutation framing is consistent with annotations, so there is no contradiction.

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

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

Two sentences pack the core action, required and optional fields, GraphQL operation, and permission requirement without fluff. Each clause earns its place, and the mutation marker is front-loaded.

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

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

Names all relevant parameters and the permission requirement, but with no output schema, 'addComment(comment) → union' is thin for understanding success/error results. The incorrect required-parameter claim also adds ambiguity that keeps it from being fully complete.

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

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

Schema coverage is 100%, so the baseline is 3; however, the description largely repeats schema field descriptions and adds a harmful inconsistency by listing threadSortOrder as required even though the schema marks it optional with a default of 0. This can mislead an agent into sending or requiring an unnecessary parameter.

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 an explicit action ('add a comment') and target ('meeting discussion thread'), and flags the operation as 'MUTATES Parabol data'. This clearly differentiates it from siblings like create_task, create_reflection, and generic parabol_graphql.

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?

Clear context: use when posting a comment to a Parabol meeting discussion, optionally as a threaded reply or anonymous. It does not explicitly name alternatives or state when not to use it, 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?

Annotations already mark destructiveHint=true, and the description reinforces this with 'MUTATES' and the required MEETINGS_WRITE permission. It also discloses the GraphQL mutation endpoint and content length constraint, adding useful behavioral 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?

The description is tightly packed, front-loads the mutation intent, and every sentence contributes: purpose, required inputs, content constraints, endpoint, and permission. There is no filler or redundancy.

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

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

It provides the core invocation details, endpoint, and permission, but the sortOrder 'required' conflict with the schema is a meaningful gap. With no output schema, a brief note on the response shape would have made it more complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful details like content being a stringified TipTap/ProseMirror document up to 2000 chars and sortOrder being a Float, but it incorrectly lists sortOrder as required while the schema does not mark it required.

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

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

The description states a specific action ('add a reflection card'), a specific resource ('a running retrospective's reflect phase'), and confirms it mutates Parabol data. This clearly differentiates the tool from siblings like create_task or add_comment.

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 to use the tool: adding a reflection to a running retrospective's reflect phase. It also includes a permission requirement (MEETINGS_WRITE) but does not explicitly name alternatives or state when not to use it.

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

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

The description goes beyond the destructiveHint annotation by explicitly saying "MUTATES Parabol data" and requiring TASKS_WRITE. It also clarifies how plaintextContent and content relate, which helps the agent understand what will be sent. No contradiction with annotations.

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

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

The description is compact, front-loaded with the mutation warning, and packs required/optional fields, content formats, GraphQL endpoint, and permission into a few sentences. It is slightly dense and contains the status-required inaccuracy, but overall it is 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 10-parameter mutation with no output schema, the description plus rich input schema cover the key invocation details: required context, optional links, content types, and permission. It does not describe the return value or error behavior, but annotations and schema carry enough of the 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 coverage is 100%, so the baseline is 3. The description adds useful semantics about plaintextContent versus content and optional linking fields, but it also inaccurately says status is required when the schema lists it as optional with a default. This reliability issue keeps it at 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 clearly states the tool's job: "create a task on a team" and explicitly flags it as a Parabol data mutation. It is easily distinguished from siblings like update_task or list_tasks by the verb and 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?

It gives direct usage context: required teamId, status values, optional userId/meetingId/discussionId links, and the TASKS_WRITE permission requirement. It does not explicitly name alternatives like update_task for existing tasks, but the create/update distinction is clear.

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

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

The readOnlyHint annotation already indicates a safe read, and the description adds meaningful behavioral detail: it returns nested phases/stages, retrospective extras, uses __typename for discriminating meeting types, and requires MEETINGS_READ. This goes beyond the annotation and helps the agent understand what will happen when invoked.

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 front-load the core purpose, then add conditional return details and GraphQL/auth context. Every sentence contributes distinct value with no repetition or filler.

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

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

For a single-parameter read tool with no output schema, the description explains the returned structure (phases, stages, retrospective fields, counts), the GraphQL access pattern, and the required permission. This is sufficient for an agent to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so the meetingId parameter is already fully documented in the schema. The description's 'by id' phrasing aligns with the parameter but does not add new semantic detail beyond what the schema provides. The baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Fetch one meeting by id', which clearly distinguishes this single-meeting fetch from list siblings like list_meetings and list_active_meetings. It also details what is returned, including phases/stages and retrospective-specific data, making the tool's scope 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 clearly states the tool fetches one meeting by id, which implies it is for retrieving a specific meeting rather than listing meetings. It does not explicitly name alternatives or provide when-not-to-use guidance, but the single-meeting framing is sufficient context for correct selection.

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

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

Annotations already mark readOnlyHint=true, and the description adds value by naming the backing GraphQL query and specifying the ORGS_READ and TEAMS_READ permission requirements. This goes beyond the structured annotations and helps the agent anticipate access failure modes.

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

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

The description is two short sentences: the first states the core action and result scope, the second adds endpoint and permission context. Every sentence earns its place with no filler.

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

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

For a simple, single-parameter read operation, the description covers the key facts: what is fetched, that teams are included, the endpoint, and permissions. No output schema exists, but the description gives enough about the return scope to guide the agent.

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

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

Schema coverage is 100%, with orgId already documented as 'The organization id.' The description's 'by id' adds no new semantic detail, so the baseline of 3 applies since the schema carries the parameter meaning.

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

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

The description uses a specific verb ('Fetch') and resource ('one organization by id'), and clearly distinguishes from list_organizations by emphasizing a single organization. Including 'its teams' further clarifies the scope of the result.

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 phrase 'by id' provides clear context for when this tool is appropriate: when the agent has a specific organization id. It does not name sibling alternatives like list_organizations, but the singular-by-id framing implies the correct selection criterion.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds value beyond that by disclosing the exact GraphQL query path (viewer.team(teamId)) and the permission scopes required (TEAMS_READ, plus conditional MEETINGS_READ and ORGS_READ). It also exposes what data will be included in the result, which is helpful behavioral context.

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

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

The description is compact: the first sentence communicates the core action and result content, and the second adds the essential GraphQL and permission context. It is front-loaded with the most important information and contains no filler or redundant restatement of the title.

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

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

With a single well-documented parameter, readOnly annotation, and no output schema, the description carries the full responsibility for return-value context. It does so by explicitly listing the included sub-resources and the permission prerequisites, making it complete enough for an agent to select and invoke the tool correctly.

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

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

The only parameter, teamId, has full schema description coverage with 'The team id.' The description adds nothing semantically beyond the schema because it only refers to 'by id' without giving format, example, or source guidance. Baseline 3 is appropriate because the schema already documents the parameter adequately.

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 team by id'. It further defines the scope by enumerating the returned data (metadata, team members with each member's user, active meetings, and organization), which clearly distinguishes it from sibling tools like list_teams, get_meeting, and get_organization.

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

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

The description clearly frames when to use this tool: when you need a single team and its related members, meetings, and organization. It does not explicitly name alternatives or exclusions, but the id-based singular scope and the embedded permission requirements provide clear contextual 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 mark readOnlyHint=true, and the description reinforces this with 'Fetch' and 'authenticated user'. It adds useful context about the token owner and required scope. No contradiction, though null/error behavior is not discussed; the annotation lowers the bar.

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: the main purpose and returned fields, the underlying GraphQL shape, and a usage pointer. Every sentence earns its place, and there is no repetition of annotation data or filler.

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

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

For a zero-parameter, read-only identity tool with no output schema, the description covers what is returned, the required scope, and the intended starting use case. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The input schema has zero parameters, so the baseline is 4. The description correctly adds no parameter detail and instead enumerates the meaningful response fields, which is the relevant semantic content 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 opens with a specific verb 'Fetch' and names the exact resource: the authenticated Parabol user (token owner). It enumerates the returned fields (id, preferredName, email, tier, tms), making it easy to distinguish from team, organization, and meeting sibling tools.

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

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

'Start here to discover your identity and team ids' provides a clear entry-point context, and the USERS_READ scope states a prerequisite. However, it does not explicitly contrast with the generic parabol_graphql/parabol_query siblings or state when not to use this tool.

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 flag destructiveHint, and the description adds meaningful context beyond that: it explicitly says the tool mutates data, sends email invitations, and requires TEAMS_WRITE. This gives the agent important side-effect and authorization information.

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

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

The description is extremely concise, with no filler. It front-loads the mutating nature, then covers required parameters, optional parameter, GraphQL mapping, and permission requirements in three tight 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?

For a simple three-parameter mutation with no output schema, the description covers the essential invocation details: required fields, optional field, GraphQL operation, and permission. It does not discuss edge cases like duplicate invites or email validation, but these are not necessary for basic correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds slight value by restating required and optional parameters and mapping to the GraphQL mutation, but it does not substantially deepen parameter understanding beyond the schema.

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

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

The description uses a specific verb ('send'), names the resource (team invitations by email), and distinguishes the operation as a mutation. It clearly identifies the tool's core function apart from the generic parabol_graphql and parabol_query siblings.

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

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

The description states required inputs and the required TEAMS_WRITE permission, giving clear context for when the tool is applicable. However, it does not explicitly exclude alternatives or explain when to use this convenience tool versus the generic parabol_graphql endpoint.

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 safe-read nature is established. The description adds useful behavioral context by naming required permissions (TEAMS_READ + MEETINGS_READ) and the GraphQL endpoint. It doesn't describe return shape or pagination, but the annotation lowers the burden on the description.

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

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

The description is three short, purposeful statements: what it does, the underlying GraphQL query, and required permissions. No filler words; the core action is front-loaded.

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

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

For a simple, read-only, single-parameter list operation, the description covers purpose, operation source, and permissions. There is no output schema, but the description is sufficient for an agent to know when and how to call this tool correctly.

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

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

Schema description coverage is 100%, with the single parameter teamId documented as 'The team id.' The description doesn't add extra meaning to the parameter beyond what the schema provides, which aligns with the baseline for fully covered schemas.

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

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

The description states a specific verb and resource: 'List a team's currently-active (in-progress) meetings.' It distinguishes this from sibling tools like list_meetings and get_meeting by explicitly limiting scope to active meetings. The embedded GraphQL path further clarifies exactly what operation is performed.

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

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

The description gives clear context for when to use the tool: when a team's currently-active meetings are needed. It doesn't explicitly name alternatives or exclusion conditions, but the 'currently-active (in-progress)' qualifier makes the use case unambiguous relative to siblings like list_meetings.

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 provide readOnlyHint=true, and the description adds meaningful behavioral detail: newest-first ordering, default meeting types, timestamp window semantics, pagination with `after`, the underlying GraphQL field, and the required MEETINGS_READ permission. No contradiction exists.

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

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

The description is compact and front-loaded with the core action and scope, then efficiently covers defaults, pagination, GraphQL mapping, and permissions. Every sentence contributes useful information 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 read-only list tool with five parameters and no output schema, the description covers all essential invocation details: required input, default behavior, pagination mechanics, and access requirements. An agent has enough context to call this tool 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, but the description adds value by clarifying the `after`/`before` relationship ('paginate older with after'), defaulting behavior for `meetingTypes` and `before`, and emphasizing `teamIds` is required. This goes beyond the raw 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?

The description names a specific action ('List'), a clear resource ('meetings'), and a scope ('for one or more teams'), and distinguishes historical/past meetings from active ones via title and 'past/ongoing'. This makes it easy to tell apart from the sibling list_active_meetings without inspecting schemas.

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

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

The description provides clear operational context: `teamIds` is required, meeting types default to all four, and pagination direction is explained with `before`/`after`. It doesn't explicitly state when to prefer list_active_meetings, but the 'past/ongoing' framing implies the historical use case clearly enough.

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

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

The readOnlyHint already marks the operation as read-only. The description adds meaningful operational context beyond that: the required ORGS_READ permission and the underlying GraphQL query viewer.organizations. This helps the agent understand access requirements and data source.

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 deliver the operation, scope, return fields, permission, and GraphQL source without any filler. Every sentence earns its place and the core meaning is front-loaded.

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

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

For a parameterless read-only list tool, the description is complete: it states what is returned, the viewer scope, required permission, and the underlying query. No output schema exists, but the listed fields cover what the agent needs to know.

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 has zero parameters and the schema is empty, so there is no parameter ambiguity to resolve. The baseline score of 4 applies because no parameter explanation is needed.

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 ('List'), the exact resource ('organizations the viewer belongs to'), and the returned fields (id, name, tier, billingTier). This clearly distinguishes it from sibling tools like list_organization_users or get_organization.

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

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

The description clearly indicates when to use the tool: when the agent needs the organizations associated with the current viewer. It does not explicitly name alternative tools or exclusion conditions, but the viewer-scoped context is unambiguous and sufficient for this zero-parameter read 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?

Beyond the readOnlyHint annotation, the description discloses the Relay connection format, the exact data shape, pagination cursor behavior, the underlying GraphQL query path, and permission requirements. This gives an agent meaningful behavioral expectations before invoking the 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?

Two well-structured sentences deliver the core purpose, returned fields, pagination method, GraphQL source, and permission requirements with no filler. The most important information is front-loaded.

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

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

All three parameters are thoroughly documented in the schema, and the description adds the return field list and pagination contract despite there being no output schema. Combined with permission and GraphQL path context, an agent has everything needed to call the tool correctly.

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

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

Schema coverage is 100%, so the schema already fully documents orgId, first, and after. The description reinforces pagination with first + after and clarifies the cursor usage, but this largely mirrors the schema and adds little new semantic value beyond what structured definitions already provide.

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

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

The description uses a specific verb ('List'), identifies the resource ('users in an organization'), and enumerates the returned fields (role, joinedAt, tier, preferredName, email). This clearly distinguishes it from sibling tools like list_team_members and list_organizations without ambiguity.

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

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

The description provides clear context for use, including pagination mechanics and required permissions (ORGS_READ + USERS_READ). It does not explicitly name alternatives or state when not to use this tool, but the org vs. team distinction among siblings is implicit and sufficient.

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 mark readOnlyHint=true, and the description adds meaningful behavioral details beyond that: pagination via `first` + `after` DateTime cursor, the Relay connection shape, and the required TASKS_READ permission. This goes beyond what annotations reveal without contradicting 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?

Three sentences, each earning its place: scope, filter options, pagination, underlying query, and permission. Text is compact and front-loaded with the action and resource. Not maximally structured, but well within acceptable limits.

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 does a good job conveying the output context via 'Relay connection' and the underlying GraphQL query. It covers most filter dimensions and pagination, though it omits the `includeUnassigned` option and any detail about returned task fields. Minor gap given the tool's simplicity.

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 adds helpful context by grouping the filter semantics and clarifying the pagination relationship between `first` and `after`, but it doesn't substantially extend what the schema already documents for each parameter.

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

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

Description states a specific verb ('List') and a clearly bounded resource ('the viewer's tasks (Relay connection)'), distinguishing it from other list tools by emphasizing viewer scope. It lacks an explicit named alternative, so it doesn't fully earn the top score.

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

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

The description gives clear context for when to use this tool: when the viewer's tasks are needed, with optional filters and pagination. It does not explicitly mention when not to use it or name alternative tools, but the viewer-specific framing is enough to orient an agent.

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, and the description adds the required TEAMS_READ permission, which helps agents anticipate authorization failures. It also discloses the exact response shape. It does not discuss pagination or sort behavior, but for a read-only list tool the added context is sufficient.

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

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

The description is compact and front-loaded: it states the purpose, output fields, underlying query, and required permission in two sentences. Every sentence adds value, and there is no redundant information.

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

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

Despite having no output schema, the description explicitly lists the returned fields (role flags, preferredName, email) and the required authorization. It is complete for a simple read-only list operation, though it omits details like default sort order or error handling, which are minor given the schema 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%, so the schema already documents both 'teamId' and 'sortBy'. The description does not add new parameter semantics beyond restating that the teamId is used and that members are sorted by the optional field, so a 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 ('List'), a specific resource ('the members of a team'), and the exact data shape returned (role flags, underlying user fields). It also provides the underlying GraphQL query, which distinguishes it from siblings like 'list_teams' or 'list_organization_users' by making the resource scope 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 clearly implies when to use this tool—when you need team membership with role and user details. It provides contextual clues like the required permission and GraphQL query, but it does not explicitly mention alternatives or state when not to use it, 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?

Annotations declare readOnlyHint, and the description adds useful behavioral context: it names the GraphQL source (viewer.teams), the required auth scope, and the exact fields returned. It stops short of describing pagination or response shape, but for this simple read operation the added context is strong.

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

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

Two sentences front-load the core purpose and output fields, then add the data source and auth requirement. Every sentence earns its place with no redundant wording.

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 operation with one optional parameter, the description fully covers purpose, output fields, data source, and required scope. No output schema exists, but the field list in the description compensates well.

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 only parameter, includeArchived, is fully described in the schema with its default value, so schema coverage is 100%. The description adds no additional parameter-level meaning beyond what the schema already provides, placing it at the baseline score.

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 clear verb and resource: lists the teams the viewer belongs to, with specific fields. The description precisely differentiates this from sibling tools like list_organizations 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?

Clearly establishes context: this is for listing the current viewer's teams, with a TEAMS_READ scope prerequisite. It does not explicitly name alternatives or when not to use it, but the scope is specific enough for an agent to route correctly.

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 provide destructiveHint: true, and the description reinforces this with a prominent 'MUTATES Parabol data (potentially)' warning. It also discloses the escape-hatch nature, the endpoint, and token-scope requirements, adding context beyond the annotation. It does not contradict the annotations.

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

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

The description is compact and front-loads the most important behavioral warning ('MUTATES Parabol data (potentially)') before explaining purpose and usage. The phrase 'including any mutation' is slightly redundant with the mutation warning, but overall every sentence serves a clear function.

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 arbitrary GraphQL escape hatch with no output schema, the description supplies the endpoint, variable support, authentication expectation, mutation warning, and routing guidance. It is not missing information an agent needs to decide whether to call it or how 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%, with query and variables already documented in the input schema. The description adds only that variables are 'optional' and that the operation can be a query or mutation, but this does not materially expand on the schema. Baseline 3 is appropriate.

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

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

The description identifies a specific action ('run an arbitrary Parabol GraphQL operation') and resource ('action.parabol.co/graphql'), including explicit mention of mutations. It clearly distinguishes itself from curated tools and names the sibling parabol_query for read-only calls, so an agent can tell them apart.

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

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

The description explicitly states when to use this tool: 'Use for operations not covered by the curated tools.' It also gives a clear exclusion: 'Prefer parabol_query for read-only calls,' and warns that the token must carry the required scope. This is direct, actionable guidance with an alternative named.

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, and the description adds meaningful behavioral context beyond that: mutations are actively rejected, the query is sent to action.parabol.co/graphql, and valid read scopes are required on the token. This goes beyond the structured annotations without contradicting 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?

The description is appropriately sized and front-loaded with the escape-hatch framing. Every sentence contributes a distinct piece of information, though the first sentence somewhat repeats the title's read-only claim, which is already present in the annotation 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 flexible escape-hatch tool with two parameters and no output schema, the description covers the essentials: endpoint, parameter shape, rejection of mutations, alternative routing, and auth requirements. A brief note on standard GraphQL response formatting would be a minor addition but is not necessary for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that variables are optional and that the query must be a query rather than a mutation, but it does not add significant syntax or format details beyond what the schema already documents.

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 ('run'), a resource ('arbitrary Parabol GraphQL query'), a target endpoint, and explicitly labels itself an 'escape hatch' for fields not covered by curated read tools. It also distinguishes itself from sibling tools by stating mutations are rejected and routed to dedicated write tools or parabol_graphql.

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

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

It explicitly states when to use this tool ('Useful for fields not covered by the curated read tools') and when not to use it ('Mutations are REJECTED — use the dedicated write tools or parabol_graphql for those'). It also notes the token requirement for matching read scopes, providing clear selection 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 flag destructiveHint=true, and the description independently reinforces that this 'MUTATES Parabol data' while adding useful context: the required permission (MEETINGS_WRITE) and the return value (new meetingId). This goes beyond the annotation without contradicting it.

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

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

The description is two sentences with no filler. The mutation warning is front-loaded, followed by essential inputs, permission, and return value, making every sentence earn its place.

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

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

For a simple two-parameter mutation tool with no output schema, the description is reasonably complete: it names the operation, parameters, permission requirement, and return value. It could be fuller about failure modes or union response details, but those are not critical for selecting and invoking this tool.

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

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

Schema description coverage is 100% and both parameters already have descriptions. The description adds little beyond restating that teamId is required and name is optional, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'start a new Check-in (Action) meeting for a team' and notes the returned meetingId. This cleanly distinguishes it from sibling tools like start_retrospective and start_team_prompt by naming the exact 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?

The description gives clear inputs ('Required: teamId. Optionally name it') and a mutation warning, but does not explicitly say when to choose this over the sibling start_* meeting tools. The use case is implied by the meeting type name rather than stated with alternatives or exclusions.

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

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

The description explicitly says 'MUTATES Parabol data' and mentions the required MEETINGS_WRITE permission, adding meaningful behavior beyond the destructiveHint annotation. It also notes the return value (new meetingId), which helps an agent understand the tool's side effects, though it does not mention potential failure modes.

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

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

The description is compact and front-loaded with the MUTATES flag, followed by the core purpose and return value. The 'Parabol GraphQL: startRetrospective → union' detail is somewhat technical but brief, and the rest of the content is efficiently organized.

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 stating that the new meetingId is returned. It covers required parameters, optional naming, permission requirements, and the mutating nature. It could be more complete about the union response variants or failure cases, but it is sufficient for a simple two-parameter tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates the schema by saying teamId is required and name is optional, and adds no deeper semantics about formats, defaults, or constraints beyond what the schema already 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 clearly states the tool starts a new retrospective meeting for a team and returns the new meetingId, which is a specific verb+resource. It does not explicitly compare against sibling start_checkin or start_team_prompt, but the retrospective focus and GraphQL mutation name are enough to distinguish it in practice.

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 clear context for when to use the tool: starting a retrospective requires a teamId, optionally a name, and MEETINGS_WRITE permission. It does not explicitly state exclusions or when to prefer a sibling, but the required input and mutation nature make the intended use unambiguous.

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?

Clearly signals mutation with 'MUTATES Parabol data,' which aligns with destructiveHint=true and adds the specific MEETINGS_WRITE permission and underlying GraphQL mutation startTeamPrompt. This goes beyond the boolean annotation and gives the agent useful operational context.

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

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

The description is compact: three short sentences that front-load the mutation warning and then quickly cover requirements, defaults, GraphQL operation, and permissions. There is no filler or repetition beyond the useful 'MUTATES' emphasis.

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, the description covers the required parameter, the optional parameter, the permission, and the GraphQL operation. There is no output schema, but the 'union' hint provides some return-shape awareness; explicit sibling routing is the main missing piece.

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 teamId and name are already described in the schema. The description restates that teamId is required and name defaults to 'Standup,' which reinforces but does not add new semantic 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 precise action: 'start a new async Standup (Team Prompt) meeting for a team.' The resource is clearly a team and the required teamId is called out, and the meeting type distinguishes it from sibling tools like start_checkin and start_retrospective.

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 important operational context like the required teamId, optional name default, and MEETINGS_WRITE permission, but does not explicitly say when to prefer this tool over start_checkin or start_retrospective. The use case is implied by 'Standup (Team Prompt)' rather than explicitly routed.

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 flag destructiveHint=true, and the description reinforces and extends this with 'MUTATES', partial-update semantics, and an explicit TASKS_WRITE permission requirement. It does not speculate about irreversibility or side effects, but for an update tool the key behavioral warnings are 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?

Two dense sentences front-load the mutation warning, then cover required id, optional fields, partial-update behavior, GraphQL mapping, and authorization. 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?

For a mutation with one required param and several optional fields, the description gives the essential context: what changes, what stays untouched, and what permission is needed. The lack of an output schema is a minor gap, but the schema and annotations cover the remaining mechanics.

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

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

Input schema covers 100% of parameters, so the baseline is 3; the description adds the human-readable alias 'assignee (userId)' and clarifies that only included fields are changed, which is useful beyond the raw schema. The area and fields parameters are left to the schema, but they are fully documented there.

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

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

The opening phrase 'MUTATES Parabol data: update an existing task' gives a specific verb, resource, and mutation type, and 'Required: id' distinguishes this from sibling creation tools like create_task. The title confirms what the tool does, and the description makes the scope (existing task, partial update) unmistakable.

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

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

The description implies when to use it: when you have an existing task id and want to change only the supplied fields, with 'Only included fields change' preventing accidental overwrites. It does not name alternatives explicitly, 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.