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

Annotations declare readOnlyHint=true, so safety is covered. The description doesn't disclose what 'reporting' means behaviorally—whether it mutates internal auth state, what constitutes a valid outcome, or return semantics—leaving significant ambiguity for an auth-flow tool. With an output schema present, some burden is lifted, but the behavioral contract remains thin.

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 no filler. It is perhaps too terse for the complexity of an auth-flow tool, but structurally it's efficient.

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 auth-result tool with many auth-and-workflow siblings around it, the description leaves critical context unstated: the expected call sequence with workboard_auth_start_tool and workboard_auth_status_tool, what the outcome values mean, and any side effects. The output schema helps, but the description alone is insufficient 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?

There are zero parameters, so the baseline is 4. The description correctly implies no input is needed, consistent with the empty 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 verb ('Report') and a resource ('outcome of the most recent authorization redirect'), which conveys the general purpose. However, it is ambiguous whether this reports an external event's result, an intermediate auth state, or returns status data, and it doesn't distinguish itself clearly from siblings like workboard_auth_status_tool and workboard_auth_start_tool.

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

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

No guidance on when to call this versus workboard_auth_status_tool or workboard_auth_start_tool. The description says 'the most recent' redirect but doesn't explain the sequencing or conditions that make this the right 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses that tokens are stored automatically with no manual copying and states environment prerequisites. It omits what happens on repeat invocation or on failure/cancellation, so it stops short of a 5.

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

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

Front-loaded with the imperative action, then the step-by-step flow, then the follow-up call. Every sentence conveys distinct operational information with no padding.

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

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

An output schema exists, so return-value detail needn't be spelled out, and the description still notes a URL is returned. Prerequisites, the redirect mechanics, and the confirming follow-up tool are all covered for a zero-param auth starter.

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

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

The tool takes zero parameters, so the baseline is 4. The description goes slightly beyond by flagging the environment-variable prerequisite, though there are no parameter semantics to clarify.

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 ('Begin browser authorization and return the URL'), and distinguishes it from the sibling tools that follow it (auth_status, auth_result) by describing its role as the entry point of the flow.

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?

Explicit sequencing: open the returned URL, user approves, tokens stored automatically, then call workboard_auth_status_tool to confirm. It also names prerequisites (OAuth mode, WORKBOARD_OAUTH_REDIRECT_URI), leaving nothing to inference.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds that the tool performs a live verification via GET /user (an external call with latency), reports token storage location and active auth mode, and returns remediation guidance. It does not discuss caching, expiry timing, or failure modes in detail, keeping it short of a 5.

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

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

Four short sentences, front-loaded with the core purpose and the 'Call this first' directive. Every sentence carries distinct information: purpose, ordering, returned facts, and remediation.

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 status probe with an output schema already present, the description covers everything an agent needs: when to call it, what it inspects, and what to do on failure. Return-value enumeration is slightly redundant with the output schema but harmless.

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

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

The tool takes zero parameters, so the baseline is 4; there is no argument surface for the description to clarify. It correctly spends no words on parameters.

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: 'Report whether this server currently holds a usable WorkBoard credential.' The scope (auth mode, token location, existence, live verification) is concrete. It never names the nearby auth siblings (workboard_auth_start_tool, workboard_auth_result_tool), 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?

'Call this first' is an explicit ordering directive an agent can act on immediately, and 'If it is not usable, it says which tool fixes it' routes the agent to the remedy path. Both when-to-use and the fallback behavior are given, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool and largely drops it. It does not state authentication requirements, whether creation is idempotent or can duplicate cards, what happens if ai_workstream is omitted, or any side effects. Return shape is covered by the output schema, but the mutation's safety and preconditions are not.

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

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

Four short lines, front-loaded with the purpose sentence and then the three value constraints. Every sentence carries distinct information and nothing is padded.

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

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

The schema is fully described and an output schema exists, so the description need not explain fields or return values, and its constraint lines cover the trickiest inputs. It is still thin for a 10-parameter creation tool with no annotations: it never mentions that ai_description is the required card title, nor the auth/ID lookups needed to call it successfully.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real value beyond it: it converts the soft parenthetical value lists in ai_state, ai_priority, and ai_effort into hard constraints ('must be ...'). Since the schema declares no formal enums (0 parameters with enums), this imperative phrasing is the only signal that invalid values will be rejected.

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

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

The description gives a specific verb and resource — 'Create a new action item (card) on a WorkBoard workstream' — and even bridges domain vocabulary ('action item' = 'card'). This is unambiguous against siblings like workboard_update_activity_tool or workboard_list_activities_tool. However, it never names or contrasts with an alternative sibling, which is what separates a 4 from 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 use this tool versus workboard_create_workstream_tool or workboard_create_objective_tool, and no prerequisites such as obtaining a workstream or team ID first. The only guidance is value-domain constraints, which is parameter semantics rather than usage context.

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

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

No annotations are supplied, so the description carries the full burden, and it delivers: it discloses the authorization model (Data-Admin role required, instant JWT unsupported) and the lifecycle limitation that created objectives cannot be updated or deleted through the API. Output-schema presence means return values need not be re-described here.

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

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

Front-loaded with the core action, then prerequisites, then the team constraint, then the key-result shape. Sentences are short and purposeful, though the key-result field list is restated from the schema and the team-objective rule slightly overlaps the `team` parameter description.

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

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

For a 9-parameter creation tool with an output schema, the description covers auth, variant selection, required team linkage, and key-result composition, which is enough to call it correctly. It stops short of error or partial-failure behavior (e.g. what happens if one key result is invalid), the only notable remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including permission defaults and date formats; this is the baseline-3 case. The description corroborates the key-result shape (name plus optional start_value, target_value, unit_type with examples) but adds little that the schema does not already state.

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

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

Opens with a specific verb+resource ("Create a new objective with optional key results") and immediately scopes the two variants it can produce (Team or Individual). It is clearly distinguishable from the read-side siblings like workboard_get_objectives_tool and workboard_get_objective_details_tool.

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

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

States hard prerequisites (OAuth token with Data-Admin role; instant JWT tokens cannot create objectives) and a negative constraint (no update/delete exists via the API, so agents should not search for a create counterpart). It also tells the agent where to source a required input, naming workboard_get_teams_tool for team IDs, and explains the team-vs-individual condition.

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?

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the required Data-Admin role, but says nothing about duplicate-email handling, idempotency, or what is created/side effects — meaningful gaps for a mutation 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?

A single sentence that front-loads the action and appends the permission constraint. Zero filler and nothing displaced.

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?

An output schema exists so return values need not be explained, and the 100%-covered input schema handles parameters. The only shortfall is the lack of duplicate/conflict behavior for a create operation with no annotations, which keeps it just under 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%, with every property (email, first_name, last_name, designation) documented in the schema itself. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new WorkBoard user'), which cleanly separates it from the sibling read/mutate tools (get_user, list_users, update_user). It stops short of naming an alternative or scope boundary, 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?

The parenthetical '(requires Data-Admin role)' gives a real eligibility precondition, which is more than most siblings offer. However, it gives no guidance on when to prefer this over update_user, or what to do if the user already exists, so usage is only implied.

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

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

With no annotations, the description carries the full behavioral burden and usefully discloses the required team manager/co-manager permission, which is non-obvious. It does not cover other behavioral traits such as idempotency, name uniqueness constraints, or failure modes, leaving some gaps for a mutation 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 short sentences, front-loaded with the primary action and followed by the permission prerequisite. Every word earns its place with no redundancy 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?

Given the simple create operation, 100% schema coverage, and an output schema that handles return values, the description supplies the essential permission context. It is nearly complete, missing only optional guidance on when to update versus create or additional failure conditions.

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

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

Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides; the baseline of 3 applies when the schema does the heavy lifting.

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

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

States a specific verb ('Create') and resource ('workstream') plus scope ('for a team'). The create verb clearly differentiates it from sibling tools like workboard_update_workstream_tool and workboard_get_workstreams_tool without needing to inspect their schemas.

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

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

Description provides clear context ('Create a new workstream for a team') and a critical prerequisite ('Requires team manager or co-manager permissions'). It does not explicitly name alternatives (e.g., update_workstream) or when not to use it, but the creation intent is 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?

readOnlyHint=true already tells the agent this is a safe read, and an output schema exists, but the description adds no behavioral context of its own -- no note on what happens if the ID does not exist, required permissions, or any other trait. It essentially restates the schema.

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

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

One short sentence, front-loaded with the verb and resource, and every word earns its place. No padding or redundancy.

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

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

For a single-parameter read tool with an output schema and safety annotations, the definition covers what an agent needs to invoke it correctly. Only a brief note on missing-ID behavior or discovery via the list tool would make it 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 single activity_id parameter is fully documented in the schema including its positive-integer constraint. The description's 'by its ID' adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (WorkBoard action item) with clear scope -- a single item, not a collection. This implicitly distinguishes it from list-oriented siblings like workboard_list_activities_tool, though it never names them explicitly.

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

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

The phrase 'by its ID' implies usage context (call it when you already have a known ID and need the full item), but there is no explicit when-to-use vs alternatives guidance and no mention of the list tool for discovery. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds meaningful behavior beyond that: the default year scoping and the include_prior_years override, plus the shape of returned data (names, current values, targets, IDs). No auth or pagination notes, but the added context is substantive.

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

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

Three short, front-loaded sentences: purpose, usage pairing, then the scoping caveat. Every sentence carries information and nothing is padded.

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

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

Read-only annotations plus an output schema mean safety and return formatting need no elaboration; the description nonetheless sketches the returned fields. For a zero-required-parameter list tool, nothing an agent needs to call it correctly is missing.

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

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

The single parameter is already fully documented at 100% schema description coverage, including its default. The description restates the default-year behavior, which is helpful reinforcement but adds no new semantics, so baseline 3 applies.

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

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

States a specific verb ('List'), resource ('key results (metrics)') and scope ('the current user owns or has access to'), which separates it from the sibling workboard_get_user_key_results_tool. An agent can identify what this returns 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?

Explicitly states the use case ('find metric IDs and see current progress before updating with workboard_update_key_result_tool'), naming the paired mutation tool. It lacks an explicit 'when not to use' or a direct pointer to the user-scoped sibling, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, and the description adds genuinely new behavior: it auto-resolves the current user and discovers objectives through their key results rather than requiring IDs. It does not mention rate limits or result-set size, but with annotations and an output schema present the remaining burden is small.

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 with the resource and the recommendation front-loaded; every sentence earns its place and there is no restating of the title or schema.

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

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

With readOnlyHint annotations, a fully described single parameter, and an output schema covering return values, nothing an agent needs to call this correctly is missing. The auto-discovery behavior — the one thing not expressible in schema — is stated.

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

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

Schema description coverage is 100% and the single optional parameter is fully documented there, so the schema does the heavy lifting. The description reinforces the no-ID default and the key-result discovery path, which adds a little meaning but no syntax or format detail beyond the schema — baseline 3.

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

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

States a specific verb and resource (get the current authenticated user's objectives with key results) and explicitly scopes it to the current user, which separates it from workboard_get_objectives_tool and workboard_get_user_key_results_tool. An agent can select it without opening the schema.

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

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

Gives a clear triggering condition — 'when users ask about "my objectives" or "my OKRs"' — and labels itself RECOMMENDED, plus notes 'no IDs needed' which implicitly contrasts with ID-driven siblings. It stops short of naming the alternative tool or stating when NOT to use it, so it is not a full when/when-not treatment.

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

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

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description adds the scope of retrieval (objective metadata plus all key results with targets, progress, update schedules), but since an output schema exists, enumerating return fields is largely redundant rather than additive behavioral context.

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

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

Three short sentences, front-loaded with the core purpose, then the return scope, then the prerequisite. Nothing is padded, though the return-field enumeration is partly duplicated by the output schema.

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

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

With readOnlyHint covering safety, a full output schema covering returns, and 100% schema coverage on the two required params, the description supplies what an agent still needs: the objective-plus-key-results scope and the prerequisite lookup for user_id. Only sibling-selection guidance is missing.

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

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

Schema description coverage is 100% and both parameters are documented there, including the pointer to workboard_get_user_tool for user_id. The description repeats that pointer but adds no format, range, or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Get full details for a single objective including all its key results.' The word 'single' implicitly separates it from the list-style siblings (workboard_get_objectives_tool, workboard_get_my_objectives_tool), but no sibling is named, so differentiation is inferred rather than explicit.

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

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

Gives one concrete precondition ('Use workboard_get_user_tool (no arguments) to find the current user's ID'), which is genuinely useful. However, it offers no guidance on when to choose this tool over workboard_get_objectives_tool or workboard_get_user_key_results_tool, which overlap in the key-results domain.

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

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

readOnlyHint=true already declares the safety profile, so the description's job is to add behavior beyond that. It does: it discloses that all owned objectives are returned (not a filtered subset), mentions full pagination, and notes that workstreams and status_color appear only when present, which is useful variance 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?

Four short sentences, the core purpose front-loaded before the return-shape note and the two lookup hints. Every sentence carries information the agent can act on; nothing is restated from 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?

An output schema exists, so return values need not be explained, and the description still adds the conditional-field and pagination nuance. The one loose end is that 'with full pagination' does not say whether all pages are fetched automatically or the caller must page through results.

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

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

Schema coverage is 100%, so the baseline is 3; however the description adds a resolution path the schema lacks, pointing to workboard_get_team_members_tool for name/email lookup. It does not add type, range, or format constraints beyond the schema's positive-integer/minimum-1 definition.

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+scope: objectives owned by a given WorkBoard user, keyed by user ID. It does not, however, differentiate itself from the close sibling workboard_get_my_objectives_tool or workboard_get_objective_details_tool, so an agent must infer that this is the 'arbitrary user ID' variant.

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

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

Gives concrete context for obtaining the required argument, naming two routes (workboard_get_user_tool for the current user, workboard_get_team_members_tool to resolve a name or email). It stops short of stating when to prefer this over workboard_get_my_objectives_tool, so no explicit 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds value by disclosing what comes back (user IDs and emails) and how the result chains into other tools, but says nothing about pagination, empty-team behavior, or result size limits.

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

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

Two tight sentences: the purpose and output are front-loaded, then the usage and chaining guidance. No filler or restated naming.

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 an output schema present, return shape needn't be explained, and the description covers purpose, resolution use case, and downstream chaining. Only minor operational details (pagination, large teams) are absent.

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

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

Schema description coverage is 100% and the single team_id parameter is already documented in the schema, including where to obtain it. The description adds no format or semantics beyond that, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Get all members of a WorkBoard team') and even names the returned fields (user IDs and emails), so the agent knows exactly what it fetches. It doesn't explicitly contrast itself with the closest sibling workboard_get_teams_tool, though the schema does route team_id retrieval there.

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

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

It states a concrete use case ('resolve a person's name or email to their WorkBoard user_id') and a follow-on call ('Combine with workboard_get_objectives_tool(user_id) to fetch their OKRs'), which is clear routing guidance. It stops short of an explicit when-not-to-use or an alternative sibling for listing users.

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

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

Annotations only cover readOnlyHint=true, so the description carries the rest and does so well: it discloses that sub-team objectives are excluded, that the date semantics are overlap-based with past quarters included, and a costly performance trait ('slow... takes about a minute'). Latency and scope-exclusion disclosure is exactly the behavioral context an agent needs before invoking.

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 paragraphs, each earning its place: core behavior and window semantics first, then the decision context, then the prerequisite. 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?

With an output schema present, return values need no explanation. Scope rules, exclusions, latency expectation, and the prerequisite lookup tool are all covered, leaving nothing an agent needs missing before calling it.

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

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

Schema coverage is 100% and all three parameters are documented with format patterns and inclusive-window semantics, so the baseline is already met. The description adds the non-obvious selection rule that the window matches on date overlap rather than containment, which is meaningfully more than the schema provides.

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

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

States a specific verb and resource plus the key scope rule: a team's objectives whose dates overlap a window, past quarters included. The sub-team exclusion further sharpens the scope. However, it never names or contrasts with the closely-related siblings workboard_get_objectives_tool and workboard_get_my_objectives_tool, so sibling discrimination still requires inference from the name.

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

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

Gives a concrete use case ('quarterly OKR reviews or snapshots, e.g. Q1 after March 31') and routes the agent to workboard_get_teams_tool for obtaining team IDs. It stops short of stating when NOT to use it or which sibling to pick for non-team-scoped objective queries.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds a genuine behavioral constraint beyond the annotation: results are limited to teams the authenticated user belongs to, so it is not a global team listing. It says nothing about pagination, result limits, or sort order for a list operation.

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

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

Front-loaded with the core action and scope, then the sibling routing cue — no filler sentences. The middle sentence describing return fields (IDs, names, owner user IDs) is largely redundant given an output schema exists, so it does not fully 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 zero-parameter read tool with a full output schema and readOnlyHint, the description covers purpose, scope, and the relevant alternative. The only omissions are list-behavior details such as pagination or result-size expectations, which are minor here.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The scope statement ('authenticated user belongs to') usefully explains that no filter parameter is required or available.

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 (Get) and resource (teams) with an explicit scope: teams the authenticated user belongs to, not all teams. It also names the sibling workboard_get_team_members_tool, so an agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent: use workboard_get_team_members_tool when the full member list (with user_ids) for a specific team is needed. That gives a clear alternative with its selecting condition, though there is no stated 'when not to use' or prerequisite (e.g., auth) 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?

readOnlyHint=true already establishes the safe read-only profile, and the description does not contradict it. It adds the ID-resolution prerequisite but no pagination, result-size, or failure-mode context; with annotations covering safety, this is adequate but not 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 short sentences, purpose front-loaded, prerequisite immediately after. 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 single-parameter read-only lookup with an output schema present, the description need not explain return shape. Purpose plus the ID-sourcing prerequisite covers everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single team_id parameter is documented as a positive integer in the schema itself. The description adds no format or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get all workstreams') plus a scope qualifier ('belonging to a specific team'), which lets an agent distinguish it from workboard_get_workstreams_tool. It stops short of naming that sibling explicitly, so it falls just under a 5.

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

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

The second sentence gives a concrete prerequisite workflow: use workboard_get_teams_tool to obtain a team_id first. That is clear context for invoking the tool, though it offers no when-not-to-use guidance or alternative retrieval paths.

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

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

Annotations declare readOnlyHint=true, so safety is covered. The description still adds useful behavioral context beyond that: the default result scope is current-year only, and the tool is deliberately limited to WorkBoard user IDs rather than names/roles. It does not need to describe returns because an output schema 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?

Front-loaded with the core action in the first sentence, then layered usage notes and a default-behavior caveat. The 'Skills layer' sentence is slightly tangential but earns its place by preventing a common misuse (passing a role instead of an ID).

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 read tool with full schema coverage, readOnlyHint, and an output schema, the description covers purpose, usage, ID resolution path, and default filtering. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and both parameters (user_id, include_prior_years) are already documented in the schema, so baseline 3 applies. The description restates the user-ID provenance and the prior-years default, adding only the organizational context that IDs must be sourced elsewhere.

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

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

States a specific verb (List), resource (key results/metrics), and scope (for a specific WorkBoard user by user ID). The scope phrase 'for a specific WorkBoard user' implicitly separates it from the sibling workboard_get_my_key_results_tool, so an agent can pick correctly 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 use case ('review a direct report's key results before a 1:1'), names the prerequisite tools (workboard_get_teams_tool, workboard_get_team_members_tool) for resolving a name to a user ID, and warns that the skills layer — not this tool — maps roles like 'direct report' to IDs. Clear when-to-use plus prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the defaulting behavior (omitting user_id returns the current authenticated user), which is useful. However, it doesn't discuss error behavior (e.g., invalid ID), auth requirements, or response shape beyond what annotations provide.

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

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

A single, front-loaded sentence that covers both modes of operation. 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 simple single-parameter read tool with an output schema and read-only annotation, the description covers the essentials. It could mention authentication prerequisites or the shape of the returned user, but those are minor given the low complexity.

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

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

Schema description coverage is 100%, and the schema already documents user_id fully, including the default behavior. The description repeats that behavior, adding no new syntax or edge-case guidance. Baseline 3 is appropriate when the schema is complete.

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 (Get) and resource (WorkBoard user), with the dual scope (by ID or current user). It doesn't differentiate itself from siblings like workboard_get_my_objectives_tool or workboard_get_user_key_results_tool, but the resource is clear.

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

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

Implied usage: omit user_id to get the current user. The description doesn't state when to use this vs. workboard_list_users_tool or workboard_get_team_members_tool, and there are no explicit exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the response includes workstream metadata and every action item with detailed fields, which is useful scope context, but it does not discuss volume, pagination, authentication, or rate limits.

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

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

The description is two sentences, front-loaded with the core operation and then the returned contents. Every clause earns its place and there is no redundant or vague padding.

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

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

Given the simple one-parameter read operation, the readOnly annotation, and the presence of an output schema, the description is nearly complete. Its main omission is usage guidance relative to sibling retrieval tools, which prevents a perfect score.

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

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

There is only one parameter, ws_id, and the schema description coverage is 100% with a clear positive-integer definition. The description adds no new syntax, format, or meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states a specific verb and resource: get a workstream's full details and all action items. It distinguishes the scope from basic activity retrieval by emphasizing full workstream detail, but it does not explicitly name sibling alternatives such as list_activities or get_activity.

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 retrieval of comprehensive workstream information, but it provides no explicit when-to-use guidance, no prerequisites, and no alternative tools for narrower queries. An agent must infer this from the name and scope statement alone.

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

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

Annotations only supply readOnlyHint=true; the description goes further by disclosing the non-obvious derivation mechanism and the incompleteness of results (empty columns are silently omitted). It does not mention ordering, permissions, or pagination, but for a read-only lookup it adds meaningful 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?

Three short sentences: purpose first, mechanism second, usage tip third. Every sentence earns its place and there is no filler or repetition of 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?

With an output schema present and annotations covering the read-only profile, the description need not explain return values, and it correctly focuses on the surprising behavior (columns absent when empty). The only minor gap is the absence of any note on column ordering or how column_id ties back to action items accessible via other tools.

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

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

Schema description coverage is 100% with a single ws_id parameter already documented as a positive integer, so the schema carries the load. The description's mention of the 'workstream's action items' loosely ties ws_id to a workstream, but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a precise verb+resource: 'Get the custom Kanban columns in use on a workstream.' The added detail that columns are derived read-only from the workstream's action items makes it uniquely identifiable among the sibling tools, none of which return columns.

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?

Explains the motivating context ('The API has no column endpoint, so columns are read off the workstream's action items') and a key caveat for interpreting results ('A column with no cards in it will not appear'). It also tells the agent what to do with the output ('Use the column_id values to tell which column a card sits in'), though it names no alternative tool for retrieving column metadata another way.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds real scope semantics beyond that (all accessible team workstreams, personal ones excluded), but it says nothing about pagination, ordering, or result limits despite returning 'all' workstreams.

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

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

Front-loaded with the core action and appropriately short. The second sentence partially restates the first ('team workstreams' vs 'workstreams the user has access to'), which is mild redundancy but not harmful.

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 an output schema present, return values need no explanation, and the description covers scope and the optional filter. The one remaining gap is distinguishing this tool from the similarly named team-workstreams sibling.

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 single ws_id parameter is already fully documented as an optional workstream ID filter. The description merely restates that optional filtering exists, adding no syntax or edge-case detail beyond the schema.

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

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

States a specific verb and resource (get team workstreams) and clarifies scope by excluding personal workstreams. It does not name or differentiate itself from the close sibling workboard_get_team_workstreams_tool, leaving the agent to infer the distinction.

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

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

The description implies when to use the tool (browsing all accessible workstreams) and notes the optional single-ID filter, but offers no explicit when-not guidance or routing to the team-workstreams sibling. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely new behavioral context not present in the schema: a server-side default page size of 15 and the fact that results are scoped to the authenticated user's access. It stops short of describing auth prerequisites or result ordering.

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 core behavior, then defaults, then pagination and filtering. Nothing is redundant and every sentence carries information an agent can act on.

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

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

With an output schema present, return shape need not be explained, and the description covers defaults, pagination, and filtering. The remaining gap is sibling routing — nothing tells the agent how this differs from the other activity-listing tools.

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

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

Schema coverage is 100% and the schema already documents each parameter, including the allowed enum values for state, effort, and priority. The description restates those filters in prose without adding format, precedence, or combination semantics, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('List action items') and scopes it to items accessible to the authenticated user, which is meaningful for a multi-tenant workboard system. It does not differentiate itself from siblings such as workboard_get_activity_tool (single item) or workboard_get_workstream_activities_tool (workstream-scoped list), so the agent must infer the boundary.

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

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

The description gives concrete usage mechanics (pagination via limit/offset, filtering by owner/state/priority/effort) but never says when to choose this tool over workboard_get_workstream_activities_tool. Usage is implied rather than contrasted with alternatives.

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 the read-only nature, and the description adds genuine behavioral context on top: the authorization requirement for org scope, the 100-user result cap, and the paging controls. It does not describe ordering, error behavior, or what happens when offset exceeds the result set.

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

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

One-line purpose statement followed by two tight sentences covering scope semantics and pagination. Zero filler, and the most decision-relevant fact (default scope works for any account) is front-loaded.

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

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

With an output schema present, return-value detail is unnecessary, and the description covers the pieces an agent must know before calling: scope, auth prerequisite, and paging. Only edge-case behavior (ordering, over-large offsets, token-missing failure mode) is left uncovered.

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 earns above baseline by explaining the functional consequence of scope (which users are visible, and why org needs a token) and by tying limit/offset together as a paging pair rather than restating the 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 and resource ("List WorkBoard users") and immediately scopes it by team vs. org visibility, which separates it from mutation siblings like create_user/update_user. It does not, however, explicitly distinguish itself from overlapping read siblings such as workboard_get_team_members_tool or workboard_get_user_tool, leaving the choice to inference.

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

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

Gives clear selection criteria between the two scope values and states the prerequisite for the broader one ("scope='org' ... requires a Data-Admin token"), plus the paging mechanism. There is no explicit when-not-to-use or named alternative among the sibling list, so it stops short of a full routing rule.

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

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

With no annotations provided, the description carries the full burden and does disclose real behavior: a read-before-write existence check and partial-field update semantics. It does not mention permissions/auth requirements or what happens on a failed lookup, so it is strong but not complete.

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

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

Two short paragraphs, front-loaded with the core action and followed by the behavioral notes. Efficient overall, though the trailing enumeration of valid state/priority/effort values duplicates schema content and is mildly redundant.

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 mutation tool with an output schema present, the description covers the operation, the partial-update semantics, and the read-before-write validation. What remains missing is auth/permission context and failure behavior, which matters given no annotations exist.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description restates the state/priority/effort allowed values, which adds essentially nothing beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The definition opens with a specific verb+resource: 'Update an existing WorkBoard action item.' Combined with the tool name, this clearly distinguishes it from siblings like update_workstream_tool, update_user_tool, and create_activity_tool. An agent can tell exactly what object this mutates.

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 clarifies the semantics of the operation ('Only provided fields are updated'), which implies partial-update usage, but never states when to reach for this tool versus get_activity or create_activity, nor any prerequisites. Usage is implied rather than spelled out.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it delivers little: nothing about permissions/auth, whether the new value replaces or accumulates against prior progress, whether check-in history is preserved, or whether the update is reversible. An output schema exists, so return values are covered, but the mutation semantics themselves remain undisclosed.

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 with no filler, and the core purpose is front-loaded ahead of the check-in context and the prerequisite. Minor verbosity from the line-wrapped phrasing ('without logging into WorkBoard'), but nothing that needs to be cut for comprehension.

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 3-parameter schema at full description coverage, an available output schema, and an explicit ID-discovery prerequisite, an agent has enough to invoke this correctly. The remaining gap is behavioral (auth/permissions, overwrite vs. accumulate), which is a real but secondary omission for this complexity level.

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

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

Schema description coverage is 100%: value, comment and metric_id are all documented in the schema, including the metric_id provenance pointer. The description only restates the concept of 'a key result's value' and adds no format, unit or constraint detail beyond what the schema already gives, so the baseline 3 applies.

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

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

States a specific verb and resource ('Update progress on a key result (metric)') and scopes the use case to weekly OKR check-ins. This clearly distinguishes it from the sibling update tools (workboard_update_workstream_tool, workboard_update_activity_tool), so an agent can pick it without opening schemas.

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

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

Explicitly names the workflow ('primary tool for weekly OKR check-ins') and gives a concrete prerequisite: call workboard_get_my_key_results_tool first to find metric IDs. It stops short of stating when NOT to use it (e.g., versus user/team-level key result tools), so it is strong context rather than full routing.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a mutation but says nothing about partial versus full updates, whether omitted optional fields are cleared, permission requirements, or reversibility. 'Existing' is the only hint that the target must already exist.

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 zero filler, which is structurally clean. However, it is under-specified rather than truly concise given the tool has five parameters and no annotations to fall back on.

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

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

For a mutation tool with no annotations, the description should clarify what can be changed and any constraints; it does none of that. An output schema exists so return values need not be explained, and the schema covers the parameters, but the behavioral picture remains incomplete.

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

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

Schema description coverage is 100%, so all five parameters (email, user_id, last_name, first_name, designation) are already documented in the schema with types and optionality. The description adds no field-level detail, so the baseline of 3 applies.

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

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

The description states a specific verb (Update) and resource (an existing WorkBoard user), which is unambiguous and matches the name. It does not, however, differentiate itself from the closely related create_user/get_user siblings beyond the obvious verb change.

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 use this tool versus workboard_create_user_tool or workboard_get_user_tool, nor any stated preconditions (user must already exist, required permissions). The agent is left to infer everything from the name.

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

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

With no annotations provided, the description carries the full burden and does disclose meaningful traits beyond the schema: an internal read-before-write existence check, the required permission level, and the valid value domains for pace, health, and priority. It omits whether the update is partial or fully replacing, and whether it is reversible, which is a meaningful gap for a mutation tool.

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

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

Front-loaded with the core purpose, then a compact block of constraints. No filler sentences, though the trailing enumeration of pace/health/priority values restates the schema descriptions rather than adding new 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?

An output schema exists, so return values need no explanation, and the description covers the remaining essentials for a 7-parameter partial-update tool: the existence check, the permission gate, and the constrained value domains. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented including the pace/health/priority value sets. The description's enumeration of those values largely duplicates what the schema states, adding little semantic detail (e.g., no date format rationale or name constraints). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Update an existing workstream's properties"), which clearly distinguishes it from workboard_create_workstream_tool and workboard_get_workstreams_tool by implication. It is clear and unambiguous, but it never names a sibling explicitly to route the agent.

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 supplies a precondition (workstream must exist, confirmed by read-before-write) and an authorization requirement (team manager or co-manager), which imply when the tool is usable. However, there is no explicit guidance on when to choose this over create_workstream or get_workstreams, and no statement about partial-update behaviour when only some properties are supplied.

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