Employee mentoring software. Goals, meetings, messages and surveys from your AI assistant.
Scored across 24 tools
Tools are cleanly organized by resource with separate manage/query pairs, and descriptions explicitly cross-reference the few edge cases (e.g. 'use cancel_match instead', 'use delete_cohort instead'). Mild surface overlap remains between stats_query and reports_query and between members_query and profile_query, but boundaries are mostly clear.
A dominant noun_manage / noun_query pattern covers 19 of 24 tools, giving the set a predictable structure. The five exceptions (cancel_match, delete_cohort, delete_report_schedule, get_match_onboarding, remove_member) switch to verb_noun and singular forms, a minor but visible deviation.
At 24 tools this sits in the heavy 16-25 range for a multi-domain mentorship platform. Each tool covers a distinct resource and has a rationale, but the surface is large enough that consolidation would likely improve usability.
Several resources are read-only with no create/update counterparts (goals_query, meetings_query, messaging_query, profile_query, stats_query), and matches_manage has no create action. Core admin workflows for members, cohorts, reports, skills, and surveys are covered, but these notable gaps would block agents asked to create goals, meetings, messages, or matches.
Send an announcement to every active member of the organization. Requires title and body. Admin keys only. Delivered in-app and by web delivery to all members, plus a Slack channel post when one is configured.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| title | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is covered. The description adds real value beyond that: the auth requirement ('Admin keys only') and the delivery fan-out (in-app, web, plus optional Slack channel post), which tells the agent the blast radius of calling this.
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, front-loaded with the effect and audience, then requirements, then delivery channels. Every sentence contributes 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 no-output-schema broadcast tool with annotations covering safety, the description covers auth and delivery sufficiently to call it correctly. The only notable gap is parameter constraints, which is captured in the parameter score rather than 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 description coverage is 0%, so the description carries the full burden, yet it only restates that title and body are required. It omits the schema's meaningful constraints (4000-char body, 120-char title), so an agent gets no format or length guidance it couldn't already infer from required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Send'), resource ('announcement'), and audience scope ('every active member of the organization'), which cleanly separates it from the sibling announcements_query. An agent can tell instantly this is the broadcast/write path rather than a read.
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 prerequisites ('Requires title and body', 'Admin keys only'), which is useful gating context, but never states when to choose this over the sibling announcements_query or any when-not condition. Usage is implied by the broadcast framing rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List announcements this organization has sent, most recent first, with the recipient count captured at send time. Optional limit (1-50, default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond that: results are ordered most-recent-first, and the recipient count is a snapshot 'captured at send time' rather than live data — useful semantics for interpreting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, fully front-loaded: what is listed and how it is ordered comes first, the parameter constraint second. No filler or 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?
For a single-optional-parameter read-only list tool with no output schema, the description covers the essentials: scope, ordering, a key returned field's semantics, and the parameter's bounds and default. Nothing needed 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?
Schema description coverage is 0%, so the description must carry the parameter. It documents the sole parameter's range (1-50) and, critically, a default of 20 that appears nowhere in the schema, which the agent needs to reason about result size.
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 (announcements) plus scope ('this organization has sent'), with added detail on ordering and the recipient-count field. It does not explicitly name or contrast with the sibling announcements_manage, so differentiation is left to the query/manage naming convention.
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 announcements this organization has sent' — an agent can infer this is the read path for sent announcements. There is no explicit when-to-use statement, no exclusion, and no mention of the announcements_manage alternative for creating or sending.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently end an ACTIVE or PAUSED match as CANCELLED; unlike pause_match this cannot be reversed with resume_match.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| matchId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-structured context: permanence, the valid source states (ACTIVE or PAUSED), the target state (CANCELLED), and the irreversibility contrast with pause/resume.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with zero filler; the terminal/permanent nature is front-loaded and the alternative is attached as a contrast clause rather than a separate sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter destructive mutation with no output schema, the description covers the critical decision facts: state preconditions and irreversibility. It leaves the reason parameter and any response/error behavior unexplained, but nothing else 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?
Schema description coverage is 0% and neither parameter is described in the schema, so the description carries the full burden. It mentions the match implicitly but says nothing about matchId format/expectations or what the reason parameter is for or its length limit.
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 (cancel/pause a match), names the resulting terminal state (CANCELLED), and explicitly positions itself against pause_match/resume_match. An agent can distinguish it from sibling lifecycle tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative (pause_match, with resume_match) and the condition that distinguishes it: this action is not reversible. That gives an agent the key routing decision, though it doesn't state preconditions such as required permissions or which roles may cancel a match.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or edit cohorts, or link/unlink matches to a cohort's cycle. Set action to "create" (requires name/startDate/endDate), "update" (requires cohortId), "assign_matches", or "remove_matches" (both require cohortId + matchIds). To delete a cohort, use delete_cohort instead — that stays a separate tool.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| action | Yes | ||
| endDate | No | ||
| cohortId | No | ||
| matchIds | No | ||
| startDate | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation/risk profile is covered structurally. The description adds which actions mutate cohort membership versus cohort metadata, but says nothing about permissions, whether update is partial, or whether unlinking matches is reversible — real gaps for a destructive 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 sentences, front-loaded with the verb/resource scope, then per-action requirements, then the sibling exclusion. No filler and nothing redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, 4-mode mutation tool with no output schema, the description covers action routing and required inputs well enough to call correctly. It is only slightly thin on what `update` can change and what a successful response looks like, though the absence of an output schema lowers 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?
With 0% schema description coverage the description must carry parameter meaning, and it does: it names the required parameters per action for 5 of the 7 parameters (name, startDate, endDate, cohortId, matchIds). It leaves `description` and the optionality/overlap of fields on the update path unstated, so it falls just short of 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?
States specific verbs (create, edit, link/unlink) against a specific resource (cohorts and their cycle matches), and explicitly names the sibling it is not (delete_cohort). An agent can distinguish it from cohorts_query and delete_cohort without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Maps each `action` value to the parameter set it requires (create→name/startDate/endDate, update→cohortId, assign/remove→cohortId+matchIds), which tells the agent exactly which branch to invoke. It also explicitly routes deletion to delete_cohort, giving a clear when-not-to-use boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read cohorts. Set action to "list" (optional phase filter) or "get_analytics" (requires cohortId).
| Name | Required | Description | Default |
|---|---|---|---|
| phase | No | ||
| action | Yes | ||
| cohortId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and openWorld=false, so the safety profile is covered. The description adds the mode contract (get_analytics requires cohortId), which is useful, but says nothing about return shape or analytics semantics; adequate rather than rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, then the usage contract. No filler; every clause carries information the agent needs to invoke correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with annotations already covering the safety profile and no output schema to explain, the description covers purpose, both modes, and all parameters. Only the shape/content of get_analytics output is left unaddressed, which is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage the description must compensate, and it does: it documents action's two values, marks phase as an optional filter, and states cohortId is required for get_analytics. All three parameters get semantic meaning beyond their bare enum/type declarations.
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 ("Read cohorts") and enumerates the two action modes with their scope, so the agent knows this is the read side of the cohorts domain versus cohorts_manage. It stops short of naming the sibling it complements, so it is clear but not fully differentiated.
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 conditional guidance: use action="list" for listing (with an optional phase filter) or action="get_analytics" when a cohortId is available. This routes invocation correctly, though it names no alternative tool for the write/other-cohort needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an unlaunched next-cohort preparation and revoke any invitations it created; cannot delete a launched or historical cohort.
| Name | Required | Description | Default |
|---|---|---|---|
| cohortId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and non-idempotent, but the description adds material context beyond them: the revocation of invitations the cohort created (a downstream side effect) and the eligibility constraint on cohort state. It doesn't state whether deletion is reversible or what errors arise on disallowed states, so 4 rather than 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?
One sentence, front-loaded with the action, then the side effect, then the eligibility limit. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-parameter tool whose annotations already cover the safety profile, the description covers action, side effects, and eligibility. Only the irreversibility/error behavior is unstated, 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 0% for the single cohortId parameter, so the description carries the burden; it implies the target is a cohort preparation but adds no format or identification detail (UUID, where to obtain it). Adequate but thin.
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 (Delete) and resource (next-cohort preparation) plus the scope of eligibility (unlaunched) and side effect (revoke invitations). An agent can distinguish this from siblings like cohorts_manage or remove_member without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the exclusion: cannot delete a launched or historical cohort, which is a real when-not-to-use rule. It doesn't name an alternative tool for those cases, so it falls short of 5, but the condition that gates invocation is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a recurring report schedule and stop its future runs from firing.
| Name | Required | Description | Default |
|---|---|---|---|
| scheduleId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered structurally. The description adds real value with 'Permanently' and the consequence that future runs stop firing, but it says nothing about auth requirements, whether the action is reversible, or what happens to already-generated reports.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that leads with the destructive verb and immediately states the operational consequence. No filler, nothing to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with annotations covering the safety profile and no output schema, the description covers what it does and its scheduling side effect. It is nearly complete, missing only a note on reversibility or required permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (scheduleId, a UUID) with 0% schema description coverage, and the description never mentions it. The name is fairly self-explanatory, so this is the minimum-viable baseline rather than a gap that genuinely confuses an agent.
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 ('Permanently delete a recurring report schedule') and clarifies the effect ('stop its future runs from firing'). This clearly distinguishes it from the sibling reports_manage/reports_query tools, though it 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?
There is no guidance on when to delete versus when to pause/disable a schedule, and no mention of prerequisites, permissions, or recovery options. The agent is left to infer that this is the terminal action for a schedule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a match's onboarding progress — welcome-screen-viewed and goal-prompt-dismissed timestamps plus first-meeting and first-goal dates; participant keys only see their own match.
| Name | Required | Description | Default |
|---|---|---|---|
| matchId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the description's extra value is the authorization rule: 'participant keys only see their own match.' That is meaningful, non-obvious behavioral context an agent cannot derive from the schema. It stops short of 5 because it says nothing about error behavior for a non-existent or inaccessible match.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence front-loads the core purpose and appends the scope constraint without padding. The semicolon clause is slightly compressed but every element (returned fields, access rule) earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the specific returned fields, and the annotations cover the safety profile, so an agent has enough to call this correctly. It is nearly complete, missing only failure/not-found behavior for an invalid or unauthorized matchId.
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 0%, but the single parameter is matchId, whose meaning is self-evident from the name and whose format is already tightly specified by the UUID pattern in the schema. The description does not add syntax or sourcing guidance beyond that, so a baseline 3 is appropriate for a single obvious identifier.
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 ('Get a match's onboarding progress') and enumerates the exact fields returned, which concretely separates it from generic siblings like matches_query and profile_query. It does not name a sibling alternative explicitly, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus matches_query, profile_query, or meetings_query, which overlap in subject matter. The only usage-adjacent content is an access-scoping note about participant keys, which is a constraint rather than a when-to-use rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read goals. Set action to "list" (optional ownerId/matchId/status filters), "get" (requires goalId), or "suggest_from_profile" (optional membershipId).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| goalId | No | ||
| status | No | ||
| matchId | No | ||
| ownerId | No | ||
| membershipId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the action-dependent parameter requirements (get requires goalId), which is useful, but says nothing about return shape, pagination, or empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence with the purpose front-loaded and the action variants enumerated in order of typical use. No filler, no restatement of the tool name.
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 three-mode read tool with six undocumented parameters and no output schema, the description covers action selection adequately but leaves filter semantics and return content unexplained. An agent can call it, but must guess at what each filter returns.
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 0%, so the description must carry the load. It does map all six parameters to their respective actions (ownerId/matchId/status to list, goalId to get, membershipId to suggest_from_profile), but only names them as 'filters' without explaining what each selects or how the status enum values behave.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Read) and resource (goals), and the action enum makes the three operating modes explicit. It does not explicitly differentiate itself from any sibling, though the _query suffix convention carries implicit contrast with the _manage tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives per-action selection guidance: use "list" with optional filters, "get" when a goalId is available, and "suggest_from_profile" with an optional membershipId. It clearly routes among the three modes, but offers no when-not-to-use guidance or alternatives (e.g. what to do if the goal is unknown).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify match state. Set action to "approve" (transition PENDING→ACTIVE), "pause" (transition ACTIVE→PAUSED), "resume" (transition PAUSED→ACTIVE), or "complete" (transition ACTIVE→COMPLETED). All require matchId. To cancel a match irreversibly, use cancel_match instead — that stays a separate tool.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| matchId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuine behavioral content: the state machine each action drives and the boundary that irreversible cancellation lives in a separate tool. It still omits side effects (e.g., notifications, downstream visibility) and permission requirements, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the operative scope statement is front-loaded before the per-action detail. The cancel_match routing closes the paragraph at exactly the point an agent would otherwise wonder about termination.
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 tool with annotations covering the safety profile and no output schema, the description covers purpose, per-action semantics, and the sibling boundary. It could still say what a successful call returns or whether any precondition (e.g., onboarding state) gates approval, but nothing essential to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden and largely does so for `action`: it explains the meaning and effect of each enum value, which the bare enum list does not convey. `matchId` is only noted as universally required, with no hint about where to obtain it (e.g., matches_query), leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (modify match state) and immediately enumerates the four supported state transitions, which distinguishes it from matches_query (read) and cancel_match (irreversible termination). An agent can identify the tool's role 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?
Each action is tied to a concrete transition (approve PENDING→ACTIVE, pause ACTIVE→PAUSED, resume PAUSED→ACTIVE, complete ACTIVE→COMPLETED), so the agent knows exactly which action applies in a given state. It also names the alternative explicitly: irreversible cancellation goes to cancel_match, not this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read matches. Set action to "list" (optional status/cohortId/format/take filters), "get" (requires matchId), "get_summary" (requires matchId), "search" (requires query), "get_suggested" (requires menteeId, optional limit), or "request_recommendations" (requires menteeId).
| Name | Required | Description | Default |
|---|---|---|---|
| take | No | ||
| limit | No | ||
| query | No | ||
| action | Yes | ||
| format | No | ||
| status | No | ||
| matchId | No | ||
| cohortId | No | ||
| menteeId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered by structured data, and 'Read matches' is consistent with it. The description adds no behavioral context beyond that — notably it does not clarify whether request_recommendations triggers any side effect, which its name hints at.
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 that opens with the verb and resource, then packs the action-to-parameter routing with no filler. The enumeration is long and run-on but every clause carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists and the description says nothing about what any action returns, so an agent cannot tell get from get_summary or get_suggested from request_recommendations beyond their parameter requirements. For a six-action dispatcher this is a meaningful gap, though the parameter routing is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden, and it does so well: it maps essentially every parameter to the action that consumes it (take/status/cohortId/format to list, matchId to get, query to search, menteeId/limit to get_suggested, menteeId to request_recommendations). It still does not explain semantics such as how 'take' differs from 'limit' or what the format/status enums mean.
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 ('Read matches') and enumerates the six sub-operations, which cleanly separates it from the write-side siblings like matches_manage and cancel_match. It never names an alternative tool explicitly, so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
For every action it specifies the required parameters (get/get_summary need matchId, search needs query, get_suggested/request_recommendations need menteeId, list takes optional filters), which is strong invocation routing. It stops short of saying when to prefer this tool over a sibling or when a given action is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read meetings and action items. Set action to "list" (optional matchId/status/take filters), "get" (requires meetingId), "list_action_items" (requires matchId, optional actionItemStatus), or "get_free_slots" (requires membershipId/fromDate/toDate, participant keys only).
| Name | Required | Description | Default |
|---|---|---|---|
| take | No | ||
| action | Yes | ||
| status | No | ||
| toDate | No | ||
| matchId | No | ||
| fromDate | No | ||
| meetingId | No | ||
| membershipId | No | ||
| actionItemStatus | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds one useful behavioral note ("participant keys only" for get_free_slots) but omits return shape, pagination behavior for take, and whether filters like status apply across 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 lead sentence front-loads the resource, and the follow-up clause enumerates the four actions with their parameter requirements in a tight, waste-free list. Every clause earns its place by documenting a mode's contract.
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 9-parameter, output-schema-less tool, the description covers the action dispatch and parameter requirements well enough to call it correctly. It is slightly thin on what each mode returns and how take/pagination behaves, but the core invocation contract is 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?
With 0% schema description coverage the description must carry the load, and it maps every one of the 9 parameters to its action and marks them required or optional (list: matchId/status/take; get: meetingId; list_action_items: matchId/actionItemStatus; get_free_slots: membershipId/fromDate/toDate). It stops short of explaining value semantics like the take limit or the status/actionItemStatus enum meanings, which the schema's enums partially cover.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Read meetings and action items") and enumerates the four operation modes, so the agent immediately understands this is a multi-mode read tool for meetings. The resource (meetings/action items) is distinct from siblings like matches_query or cohorts_query, making it separable 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?
Each action is paired with the parameter conditions that select it ("get" requires meetingId, "get_free_slots" requires membershipId/fromDate/toDate), which effectively routes the agent to the right mode. It does not, however, say when to prefer this tool over sibling query tools such as matches_query for match-linked meetings, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invite, re-invite, revoke, deactivate, change the role of, or send a reminder to a member. Set action accordingly. To fully remove a member from the org, use remove_member instead — that stays a separate tool.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | ||
| No | |||
| action | Yes | ||
| accountType | No | ||
| invitations | No | ||
| invitationId | No | ||
| membershipId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds the useful scoping fact that permanent removal is out of scope here, but says nothing about reversibility of deactivate/revoke or what happens on re-invite.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the action list and closing with the sibling routing rule. Nothing is padded and 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 7-parameter, 7-action mutation tool with no output schema and zero schema descriptions, the description is materially incomplete. The action-to-parameter mapping and per-action preconditions are the core missing content an agent needs to call this 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 0%, so the description carries the full burden, yet it only says 'set `action` accordingly'. With 7 parameters (membershipId, invitationId, email, role, accountType, invitations) it never explains which fields pair with which action, e.g. that bulk_invite needs the invitations array or that update_role needs membershipId plus role.
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 enumerates the specific operations (invite, re-invite, revoke, deactivate, change role, send reminder) against a named resource, and explicitly distinguishes itself from the remove_member sibling. An agent can tell what this tool does and does not do 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?
It gives an explicit when-not rule: full removal belongs to remove_member, which stays separate. It also tells the caller to drive behavior via `action`. What it lacks is any guidance on which parameters each action requires, so the caller still has to infer usage per action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search active org members by name, email, role, or active status.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | ||
| query | No | ||
| action | Yes | ||
| isActive | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the 'active org members' scope, but that phrasing partly conflicts with the exposed isActive parameter and says nothing about result limits or pagination, so it adds only modest 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?
One compact sentence with the search fields front-loaded and no padding. Efficient, though it is arguably too terse to be optimal for a four-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with annotations covering safety and no output schema required, the description is adequate but incomplete: it omits result shape, pagination/limits, and how the query string matches name vs email, all of which matter for a search tool with 0% 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 0%, so the description carries the burden, and it does map the meaningful fields: name/email map to query, role to role, and active status to isActive. Only the single-value 'search' action enum is left unexplained, which is negligible.
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 (Search) and resource (org members) plus the fields searched. The query/manage naming split against siblings like members_manage carries implicit differentiation, but the description never explicitly draws that boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no routing to alternatives such as members_manage or remove_member. Usage is only inferable from the verb 'Search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query messages. Set action to "list_conversations" (no fields required), "get_messages" (requires matchId; optional take/before), or "search" (requires query; optional matchId).
| Name | Required | Description | Default |
|---|---|---|---|
| take | No | ||
| query | No | ||
| action | Yes | ||
| before | No | ||
| matchId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds mode-specific field requirements but says nothing about pagination, return shape, or rate limits, which leaves behavioral context thin given no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with tight parentheticals covering all three modes. No filler; every clause carries routing 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 read-only query tool with annotations covering safety and no output schema, the description supplies the mode selection logic and param requirements an agent needs. Missing only return-format/pagination detail, which is minor given the annotation 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 0%, so the description must carry the load and largely does: it names the enum values and maps each action to its required/optional params (matchId, query, take, before). It stops short of explaining formats like the ISO datetime for `before` or take's 1-200 bound, which the schema constrains but does not describe.
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 ("Query messages") and enumerates the three action modes, so the agent understands the tool's scope. It does not explicitly differentiate itself from sibling query tools like members_query, but the action list makes the domain clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description routes the agent across the three modes by stating the required and optional fields for each (list_conversations needs none, get_messages needs matchId, search needs query). It gives clear in-tool context but no guidance on when to pick this tool over sibling query tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read profile and portfolio data. Set action to "get_profile" (optional membershipId — bio, department, seniority, skills, DEI demographics if enabled; admins can pass membershipId to view any member's) or "get_portfolio" (reflections, goal history, and badges for the calling participant only — membershipId is ignored, and admin keys are refused).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| membershipId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered; the description adds genuinely non-obvious authorization behavior — admin key refusal on portfolio and DEI demographics being conditional on a feature toggle. It stops short of describing error shapes or pagination/truncation behavior, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and the action split, with no filler sentences. The heavy parenthetical nesting makes the second half denser than ideal, but every clause carries operative information about scope or permissions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly steps in to name the returned fields per action (bio, department, seniority, skills, DEI demographics; reflections, goal history, badges). Nothing critical is missing for a read-only tool, though failure modes and result limits are 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?
Schema description coverage is 0%, so the description must carry parameter meaning — and it does: it defines both action values and their outputs, marks membershipId as optional, explains that it is ignored for get_portfolio, and notes admins may supply it to read any member. This fully compensates for the undocumented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource (read profile and portfolio data) and immediately enumerates the two concrete modes via the action enum, each with the data it returns. An agent can distinguish this from members_query/skills_query siblings because the scope is explicitly tied to profile and portfolio (reflections, goal history, badges) rather than general member records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to pick each action and the conditions that govern them: membershipId is optional for get_profile, admins may pass it to view any member, and it is ignored for get_portfolio while admin keys are refused. That is explicit when-to-use plus a when-not (portfolio cannot target another member), leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Soft-delete a member — deactivates them, detaches them from the org (clears their org membership), and frees their seat, while retaining their data; refuses on the org's last admin. Use deactivate_member to keep them attached to the org instead.
| Name | Required | Description | Default |
|---|---|---|---|
| membershipId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond them by clarifying this is a SOFT delete that retains data, enumerating the cascade (detaches org membership, frees a seat), and disclosing the last-admin refusal precondition. It also implies non-idempotent semantics by making the removal state-dependent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the operation and its consequences, then ends with the routing alternative. 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 one-parameter destructive tool with no output schema, the description covers consequences, preconditions, and the sibling alternative well. The only shortfall is the undocumented membershipId, which leaves the agent without guidance on sourcing the identifier.
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 0% and the single parameter (membershipId, a UUID) is never explained in the description — no hint about where the identifier comes from or whether it is a membership vs. user ID. With low coverage the description should compensate, and it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb (remove/soft-delete) and resource (member), then enumerates the exact side effects: deactivation, org detachment, seat release, data retention. It also names the adjacent sibling (deactivate_member) so an agent can distinguish the two without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit alternative and the condition that selects it: use deactivate_member to keep the member attached to the org. It also states a hard precondition (refuses on the org's last admin), which is exactly the guidance an agent needs before invoking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or modify reports and schedules. Set action to "generate" (kick off an on-demand report, requires format/sections/dateRangeStart/dateRangeEnd), "create_schedule" (recurring report, requires name/frequency/sections/recipients), "update_schedule" (modify an existing schedule, requires scheduleId), or "apply_program_template" (create a cohort from a template). To delete a schedule, use delete_report_schedule instead — that stays a separate tool.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| action | Yes | ||
| format | No | ||
| enabled | No | ||
| endDate | No | ||
| sections | No | ||
| frequency | No | ||
| startDate | No | ||
| cohortName | No | ||
| recipients | No | ||
| scheduleId | No | ||
| templateId | No | ||
| dateRangeEnd | No | ||
| dateRangeStart | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds real behavioral context per action (generate = on-demand, create_schedule = recurring, apply_program_template = creates a cohort), though it omits permissions, side effects on existing schedules, and return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then structured action-by-action with the redirect last; every clause earns its place. Slightly dense as a single enumerated sentence, but 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 14-parameter multi-action mutation tool with no output schema, the description covers the critical routing information (action semantics and required inputs per action). The unresolved gaps are the fourth action's required inputs and the meaning of the optional scheduling fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 14 parameters, the description carries the burden and mostly succeeds: it enumerates which parameters each of generate, create_schedule, and update_schedule requires. It falls short on apply_program_template, whose expected inputs (templateId, cohortName) and the optional parameters (enabled, startDate, endDate) are never explained.
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 pair (create/modify) and resources (reports and schedules), and explicitly distinguishes itself from the sibling delete_report_schedule. An agent can tell it apart from reports_query and delete_report_schedule without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Each action value is paired with the condition that requires it, and the one true alternative (delete_report_schedule) is named with an explicit redirect. Nothing about when to pick this tool vs its siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read reports and dashboards. Set action to "dashboard_metrics" (basic counts available on every plan), "admin_dashboard" (alias for dashboard_metrics), "dei_metrics" (demographic breakdowns for paid plans), "report_data" (full content of a report, requires reportId), "report_status" (check generation status, requires reportId), "report_history" (list past reports, optional take limit), or "list_program_templates" (seeded templates).
| Name | Required | Description | Default |
|---|---|---|---|
| take | No | ||
| action | Yes | ||
| reportId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful non-annotated context: plan gating (paid-plan-only dei_metrics) and per-action parameter requirements. It says nothing about pagination limits, throttling, or auth scopes beyond plan tier.
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 purpose followed by a single dense enumeration of actions; almost every clause carries distinct information. The one long sentence is slightly hard to scan, but no content is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 0% schema description coverage, the description does the heavy lifting by describing what each mode returns (counts, demographic breakdowns, full report content, generation status, past reports, seeded templates). Missing only edge details such as pagination behavior and the meaning of 'take' bounds.
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 0%, so the description must carry the load, and it does: every enum value is explained and the reportId dependency for report_data/report_status plus the optional take for report_history are stated. It does not explain take's 1-100 bound or reportId's UUID format, which the schema covers structurally but never describes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read reports and dashboards') and then enumerates all seven action modes with distinct meanings, so the agent knows exactly what each call returns. It does not explicitly distinguish itself from the sibling reports_manage, relying on 'Read' vs 'manage' to imply the read-only boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives per-action selection context: dei_metrics is for paid plans only, dashboard_metrics is available on every plan, report_data and report_status require reportId, report_history takes an optional take limit. It stops short of naming an alternative tool (e.g., reports_manage) or stating 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.
Modify skills and submit assessments. Set action to "create" (requires name/category, admin keys only, requires the orgSpecificSkills plan feature), "update_status" (requires skillId/status, admin keys only), or "submit_assessment" (requires skillId/level, optional matchId, participant keys only).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| level | No | ||
| action | Yes | ||
| status | No | ||
| matchId | No | ||
| skillId | No | ||
| category | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the safety profile (not readOnly, not destructive, not idempotent, closed world), so the description's job is narrower. It adds real behavioral context the annotations don't: the authority model (admin vs participant keys) and the plan-feature gate on create. It doesn't disclose what update_status does to existing skills or whether submit_assessment is repeatable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence, followed by a tight parenthetical enumeration of actions and their required fields. Dense but readable; no filler sentences. Minor cost is that the per-action requirements are compressed into one long clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-param dispatch tool with no output schema, the description covers the action space, key requirements, and plan gating well. The missing `description` param is the only substantive gap; return behavior is not described but no output schema exists to lean on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the burden and largely succeeds, mapping required fields per action (name/category, skillId/status, skillId/level + optional matchId). It omits the `description` parameter entirely, which is the one uncovered gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ("Modify skills and submit assessments") and enumerates three distinct sub-operations, which distinguishes it well from skills_query. It doesn't explicitly name skills_query as the read alternative, but the action list makes the write-side 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?
Goes beyond generic context by specifying per-action prerequisites: admin keys for create/update_status, participant keys for submit_assessment, and the orgSpecificSkills plan feature for create. This routes the caller to the right action under the right authority. It lacks an explicit "use skills_query to read" exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read skills. Set action to "list" (optional category/status filters), "search" (requires query), "get_growth" (optional membershipId — participants always see their own), or "get_match_skills" (requires matchId).
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| action | Yes | ||
| status | No | ||
| matchId | No | ||
| category | No | ||
| membershipId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds a genuine behavioral nuance beyond that: for get_growth, membershipId is optional because participants always see their own record, which is authorization context the annotations do not provide. Return format and pagination behavior are left unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence front-loads the verb and then enumerates modes in order of increasing specificity. Every clause earns its place, though the parenthetical chain makes it slightly list-heavy rather than crisply segmented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still covers every action's required and optional inputs plus the get_growth authorization nuance, which is enough for correct invocation. It omits what each mode returns and whether list results paginate, a minor gap for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load, and it does map all six parameters to their modes: action, query (required for search), category/status (list filters), membershipId (get_growth, optional), and matchId (required for get_match_skills). It does not restate enum values or UUID formats, but the schema already supplies those.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ("Read skills") and enumerates the four read modes, so an agent can immediately tell this apart from the write-side sibling skills_manage. It stops short of naming any sibling explicitly, which keeps it at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Each action is paired with its selection condition and prerequisites — "search" requires query, "get_match_skills" requires matchId, "list" takes optional filters — which is strong when-to-use routing within the tool. It gives no when-not guidance and does not name alternatives such as skills_manage, so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read mentorship stats. Set action to "mentor_stats" (mentor participant role only, optional membershipId), "mentor_moments" (mentor participant role only, self-only — membershipId is not accepted; optional unseen), "mentee_stats" (mentee participant role only, optional membershipId), or "growth_report"/"journey_timeline" (always available, optional membershipId).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| unseen | No | ||
| membershipId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare read-only/idempotent safe read. Description adds role-based access constraints (mentor/mentee participant roles, always available actions) that go beyond annotations. Lacks error behavior or return format, but meaningful context added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose and packs action constraints efficiently into one sentence. The dense parenthetical list is hard to scan but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and read-only annotations, the description covers action selection and role restrictions needed to invoke correctly. It omits return content and error cases, but those are secondary for a stats 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 0%, so description must compensate. It defines each action's meaning and maps membershipId/unseen applicability per action. It leaves 'unseen' undefined and doesn't elaborate membershipId beyond optional/not accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Read' and resource 'mentorship stats', and enumerates the action values. It does not name or contrast with sibling tools, but the action enum itself distinguishes scope.
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 per-action role requirements and parameter applicability (e.g., mentor_moments self-only, membershipId not accepted). No guidance on when to prefer this tool over sibling query tools, so not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify surveys and submit responses. Set action to "create" (requires name/type, admin keys only), "update" (requires surveyId, optional name/status, admin keys only), or "submit_response" (requires surveyId/questionId/answer, optional matchId).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| type | No | ||
| action | Yes | ||
| answer | No | ||
| status | No | ||
| matchId | No | ||
| surveyId | No | ||
| questionId | No | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-readonly, non-destructive, non-idempotent, closed-world. The description adds genuinely useful context beyond that: create/update require admin keys while submit_response does not. It does not discuss reversibility of updates or failure behavior, but the auth disclosure is a real addition.
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 pairing the high-level purpose with a scannable action-by-action breakdown. Dense but every clause carries requirements; 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 9-parameter, 3-mode tool with no output schema and zero schema descriptions, the action-mode routing is a solid foundation but the description omits the `description` parameter entirely and gives no guidance on the untyped `answer` payload. Adequate, with clear gaps.
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 0%, so the description carries the full burden. It maps required/optional params per action (name/type, surveyId, name/status, questionId/answer, matchId), which is valuable, but leaves `answer` (untyped {}), `description`, and the meaning of the `type`/`status` enum values undocumented.
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 set (modify/create/update/submit responses) against a specific resource (surveys), and enumerates the three action modes inline. An agent can immediately tell this is the write-path counterpart to the read-only sibling surveys_query.
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 per-action usage conditions: which params each action requires and which actions are restricted to 'admin keys only'. It stops short of naming surveys_query as the read-only alternative or stating when-not to use this tool, so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query surveys. Set action to "list" (optional type/status filters; participants only ever see ACTIVE surveys they are in the audience for, regardless of the status filter) or "get_results" (requires surveyId, optional matchId; participants see only their own responses; matchId filtering is rejected on anonymous surveys for non-participant callers).
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| action | Yes | ||
| status | No | ||
| matchId | No | ||
| surveyId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (which only declare read-only/idempotent/non-destructive) by disclosing participant scoping rules: participants see ACTIVE surveys regardless of the status filter, participants see only their own responses, and matchId filtering is rejected on anonymous surveys for non-participant callers. These are non-obvious authorization and result-set behaviors an agent must know.
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 and then structured by action with parenthetical qualifiers; every clause carries information. The single long sentence is dense but not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description could say more about what list vs get_results returns, but it covers actions, required/optional params, and the key permission-driven result behaviors. For a 5-param query tool with no annotations for safety semantics, this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the load: it maps surveyId and matchId to the get_results action, indicates matchId is optional, and describes type/status as filters for list. It does not characterize the values expected for type/status or explain the matchId rejection logic beyond the anonymous-survey case, leaving minor gaps.
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 ('Query surveys') and immediately decomposes the two modes the tool supports via the action enum, so an agent can tell 'list' from 'get_results' without reading the schema. It does not explicitly name its write sibling surveys_manage, so sibling differentiation is left implicit.
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 conditional guidance per action: 'list' takes optional type/status filters, 'get_results' requires surveyId and optionally matchId. It stops short of naming an alternative tool or stating when not to use this one (e.g., vs surveys_manage).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
announcements_manageannouncements_querycancel_matchcohorts_managecohorts_querydelete_cohortdelete_report_scheduleget_match_onboardinggoals_querymatches_managematches_querymeetings_querymembers_managemembers_querymessaging_queryprofile_queryremove_memberreports_managereports_queryskills_manageskills_querystats_querysurveys_managesurveys_queryEmployee surveys, performance reviews, recognition, and team pulse for AI assistants.
AI-native ITSM and ESM platform. resolve IT and HR requests inside Slack and Teams.
AI mentoring fit and book: check the fit with Marian Kamenistak and book a session in 10 minutes.
Software for your AI: company files, spreadsheets and rules, with per-person access and history.
Add one secure layer between your agents and this server.