Joxo

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

Annotations already cover the safety profile (openWorldHint=true, destructiveHint=false, readOnlyHint=false, i.e. a non-destructive write). The description adds a genuinely non-obvious behavioral trait — the call is asynchronous and the answer only arrives by then calling wait_for_teammates. It stops short of covering retraction, rate limits, or duplicate-question behavior.

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

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

Two sentences, zero filler: the first states purpose and scope, the second states the constraint and the next step. Purpose and the strongest constraint are 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?

Given a 2-parameter tool with full schema coverage and no output schema, the description supplies the remaining essentials: why to call it, when to refrain, and where the response surfaces (wait_for_teammates) rather than a return value.

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 ('question' and 'options', with its maxItems/length constraints) are fully documented in the schema. The description adds no syntax or format 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?

Specific verb ('Ask') plus target ('the team') and an explicit scope restriction ('what only a person can decide — money, scope, a plan'). It cleanly distinguishes itself from tell_people (tell vs ask) and from get_context via 'never ask what the context already answers'.

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 when to use it (decisions only a human can make), when not to ('never ask what the context already answers'), and the required follow-up ('then wait_for_teammates for the answer'), naming the sibling tool explicitly. Nothing about routing 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.

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

With no annotations, the description carries the full burden and does well: lease acquisition, refusal semantics, the takeover prerequisite, the `warning` follow-up path, and the side effect that `worktree: true` copies files but not commands. It still leaves the return shape of the first claim, permission/auth requirements, and the meaning of "warning" undefined.

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

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

Dense but front-loaded: claim semantics and refusal rules come first, then the operational conventions. Every sentence carries actionable content, though the git branch format and PR comment marker make the final third feel like a checklist appended to the core call semantics.

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 multi-device leasing tool with no annotations and no output schema, this is close to complete on the operational side. The remaining gaps are the undocumented `full` parameter and the unstated structure of the claim response and of a "warning," both of which the agent would need before acting.

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 schema alone gives no semantics for any of the 5 booleans. The description compensates for most of them, explaining `takeover` (requires person agreement and an offline peer), `details` (returned on the first claim), and `worktree` (files-only copy on the branch). Only `full` is left entirely unexplained, and `task_id` is only indirectly illuminated by the branch-naming rule.

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

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

The opening clause names a specific verb and resource ("Claim a task") and adds the distinguishing mechanic of a lease, which separates it from create_task/complete_task/list_tasks at a glance. It never explicitly contrasts itself with a sibling claim path, so it stops short of the top tier.

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 precisely when claiming succeeds, when it is refused (another device holds the lease), and the narrow condition that unlocks the alternative (device offline >15 min plus person agreement via `takeover: true`). It also routes the agent onward on a warning: "tell your person and pause_task soon," naming the sibling to invoke.

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 burden and does disclose key behavioral traits: multiple refusal conditions (missing evidence, unpushed commits, failed last test run) and a `force` override. What it omits is permission/auth requirements, idempotency, and what a rejection returns, 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?

It is compact, but the telegraphic, semicolon-chained phrasing ('Done means live', 'the rest to come') and backtick-spliced identifiers make it hard to parse and it is not cleanly front-loaded with the primary action. Compactness here comes partly at the cost of readability.

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

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

For an 8-parameter, nested-object mutation tool with no annotations and no output schema, the description covers refusal semantics and several parameters well but leaves `pr`/`full` semantics and the response behavior unstated. It is adequate on the gating logic yet incomplete for the tool's full surface.

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% across 8 parameters, so the description must compensate. It meaningfully explains `evidence` (criterion-id to link/version/check map), `partial`, `remains`, `force`, and `review`, but leaves `pr` and `full` entirely undocumented and does not clarify the nested object shape beyond a terse sketch.

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 implies a completion/marking-action ('Done means live', evidence gating, refusal), but never states plainly that it marks a task complete or names the task resource explicitly. The agent must infer the core verb+resource from the tool name rather than the text. It is distinct enough in spirit from siblings like pause_task, but the purpose is conveyed obliquely.

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 substantial conditional routing: full completion requires `evidence` for every criterion or is refused; incomplete work uses `partial: true` + `remains`; `review: true` routes to PR review. It also states the push/test preconditions and the `force: true` escape hatch. It stops short of naming sibling alternatives, 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.

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

With no annotations, the description carries the full burden and does disclose real behavior: no agent is started, `criteria` defaults to a specific set (or none when []), and the caller is notified on completion, return, or drop. It omits permission/auth requirements and what actually happens to a task created with local_job or a human work_kind.

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 core constraint ('starts no agent') front-loaded and parameter notes kept brief via backticks. Every clause carries information; the density is high but readable.

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

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

For a 6-parameter creation tool with no output schema and no annotations, the description covers the essentials (what is created, criteria defaults, notification behavior) but leaves gaps around local_job/work_kind interaction and repo defaulting that an agent must infer from the schema.

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

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

Schema coverage is only 33%, so the description must compensate and it partially does: it explains `criteria` semantics with its default value list and gives length guidance for `title` ('about 60 characters'). It says nothing about `repo`, `local_job`, or the `work_kind` values beyond what the schema already states.

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 shared task') and immediately qualifies it with 'starts no agent', which separates it from action-oriented siblings like claim_task or complete_task. It stops short of naming a sibling outright, so it is clear but not maximally disambiguating.

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 'starts no agent' clause implies when this tool is appropriate versus something that would kick off work, and the notification sentence implies it is for delegating/scheduling. However, there is no explicit statement of when to use this instead of ask_people or tell_people, 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?

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds the key behavior behind the non-read-only flag by explaining that later calls return only what is new (i.e. the unread queue is consumed), plus an untrusted-peer-content warning. It does not state that events are permanently marked as read or whether that consumption is reversible, 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?

Three short clauses, each earning its place: incremental semantics, the untrusted-data warning, and the polling instruction. The telegraphic fragment style ('Unread project events and the board') is slightly cryptic but wastes no 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?

An output schema exists, so return values need no explanation, and `remaining` is referenced consistently with that. The incremental polling model, the `full` flag, and the trust boundary are all covered; only the ambiguous 'board' concept and any consumption/acknowledgement side effect are unaddressed.

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

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

The single parameter has 0% schema description coverage, so the description must carry it, and it does: `full: true` means return everything rather than only what is new. The default (implicitly false) is only conveyed by contrast, leaving a minor 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?

The description names the resource returned (unread project events plus the board) and its incremental scope, so an agent knows this pulls team/project context rather than tasks or peers. It never states a verb and does not explicitly differentiate itself from siblings like list_tasks or list_peers, and 'the board' is left undefined, keeping it short of a 5.

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

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

It gives concrete invocation guidance: call repeatedly while `remaining` is above zero, and pass `full: true` when everything (not just new items) is wanted. No alternative tool is named as a substitute, so it stops at '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.

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

Annotations only declare a read-only, non-destructive, closed-world call, but the description discloses the genuinely non-obvious behavior that this call mutates the agent's available tool list, plus the default behavior when no group is given ("none shows the groups"). It does not say whether the added tools persist across turns or whether repeated calls accumulate or replace, which keeps it from 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?

The whole definition is one dense sentence with the effect statement front-loaded and the group enumeration trailing it. Nothing is wasted, though the parenthetical stacks make it slightly hard to scan and the tool's most important behavior (it modifies your tool list) sits mid-sentence rather than first.

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

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

For a meta/discovery tool with no output schema and a single optional enum parameter, the description covers the action, the parameter values, and the no-argument return behavior. Remaining gaps (persistence of added tools, whether groups accumulate, how many tools each adds) are real but minor for a tool whose job is simply to unlock more definitions.

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 entire parameter burden, and it does enumerate all five enum values with a hint of what each contains, plus the meaning of omitting the parameter. The hints are single words (e.g. "github (repository)"), so an agent still cannot tell exactly which tools each group adds, but the enum semantics are substantially covered.

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

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

The description states a specific resource (additional Joxo tool groups) and its effect: "`group` adds its tools to your list; none shows the groups." That is a clear, non-tautological statement of what the tool does and is distinguishable from the task/people-oriented siblings. It loses a point only because the opening phrase "More Joxo tools by group" is telegraphic and the verb 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?

The parenthetical listings (e.g. tasks: release, handoffs, stale review; team: wake, ask owner, invites) map capability areas to group values, which is usable guidance for picking an enum value. However, there is no explicit trigger for when to call this tool versus working with the already-listed siblings, and no exclusion or prerequisite stated. Usage is implied rather than directed.

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

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

Annotations already declare readOnly, openWorld, and non-destructive, so the safety profile is covered. The description adds domain context beyond that: 'usage per window (one account's headroom is not another's)', agent_tokens with 'no limit known', and this_computer_sessions meaning 'your other local sessions'. It does not cover refresh/freshness or ordering, keeping it at a solid 3.

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

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

A single dense sentence that front-loads the resource and then lists fields with parenthetical clarifications. It is efficient, though the run-on field enumeration with embedded asides makes it slightly harder to scan than a structured list.

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

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

With no output schema and no parameters, the description must explain what comes back, and it does enumerate the key returned fields (device_id, owner, online, agents, sessions, usage, agent_tokens, this_computer_sessions). This is sufficient for a zero-arg listing tool, though freshness/ordering of the data is unstated.

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

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

The tool takes zero parameters, so the baseline is 4. Evaluation instead falls on the field semantics the description supplies for the return shape, which are handled under behavioral and completeness dimensions.

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

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

The description identifies the resource precisely ('Teammates' computers') and enumerates the returned fields, so an agent can tell this lists peer devices rather than tasks or messages. It also cross-references send_message's target_device, implicitly distinguishing it from siblings. It lacks an explicit verb like 'list', but the intent is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no named alternative. The only implicit hint is that device_id is 'send_message's target_device', which suggests a workflow but is framed as field clarification rather than usage direction.

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 are present but notable: readOnlyHint=false on what reads like a pure list operation, which the description never addresses. The description does add useful behavioral context the schema lacks — ranking order, that done/dropped are only counted rather than listed, and that rows are previews — but it says nothing about auth needs or what 'openWorld' access implies.

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 and outcome, then semicolon-delimited parameter hints, with no filler sentences. The telegraphic style is dense and slightly cryptic, but 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?

With no output schema and 6 parameters at 0% schema coverage, the description should do more: pagination semantics (cursor vs limit interplay), the meaning of 'full', and the odd readOnlyHint=false are all unexplained. It covers the essentials for basic invocation but is not complete for a 6-parameter listing 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 burden, and it partially does: it explains status values ('done', 'all' or any), that task_id returns one task in full, and that cursor is the next page. However, 'full' and 'limit' are entirely undocumented in both schema and description, leaving 2 of 6 parameters opaque.

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

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

It states a specific verb+resource (lists open tasks) and even specifies the ordering ('most relevant first: yours, suggested, claimable') and the row shape ('short row each with a details preview'). This is clearly distinguishable from mutation siblings like claim_task, complete_task, or create_task, though it never names an alternative 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?

Usage is only implied through the parameter fragments ('status "done", "all" or any', 'task_id: one in full'), which tell the agent how to narrow results but not when this tool is preferred over get_context or list_peers. There are no when-not-to-use conditions or scenario framing.

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 burden. It usefully discloses the core side effect — the task is freed and becomes available to a teammate — but says nothing about whether progress is preserved, whether the action is reversible, what permissions are required, or what happens to anyone currently holding the task.

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 with no padding, and the action outcome is placed before the note guidance. The opening question is slightly cryptic but not wasteful in length.

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

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

No annotations, no output schema, and 0% schema coverage mean the description has to do the heavy lifting, yet it omits consequences (progress retention, reversibility), permissions, and sibling differentiation. For a required-parameter mutation tool in a crowded task-management toolset, that leaves real 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 coverage is 0%, so the description must compensate. It does give real semantic content for 'note' by naming the expected shape (done, next, branch), which the schema's bare string+maxLength does not. It adds nothing for 'task_id', and gives no format guidance for the note beyond the three words.

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 conveys the outcome ('free the task for a teammate') and the note's intended content, so the general intent is recoverable. But the framing is a rhetorical question ('Out of usage or stopping?') rather than a specific verb+resource statement, and it never clarifies how pausing differs from complete_task or publish_handoff among the siblings.

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

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

It hints at a trigger condition ('Out of usage or stopping?'), which implies when to reach for this tool. However, no alternative is named and no exclusion is given, so the agent must infer whether pausing beats completing or handing off.

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 burden, and it does disclose two behavioral facts: `target_device` causes a nudge on that machine (a real side effect), and content must not contain secrets. However, it says nothing about who sees the handoff, whether it requires permissions, whether it is persistent, or what the call returns.

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 plus a short constraint, all front-loaded with the core act before the mechanics. It is dense rather than padded, though fragments like 'No secrets.' and 'also nudges that computer' are terse to the point of ambiguity.

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 nested-object tool with no annotations and no output schema, the description covers what to put in the payload but omits the outcome: whether the handoff is broadcast, how it is acknowledged, and what comes back. It is the minimum an agent needs to shape a call, but not enough to predict the result.

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

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

At 75% schema coverage the schema already documents details/headline/target_device, so the baseline is 3; the description goes beyond it by explaining the two content modes ('`summary` plus `details`, or `body`') and by mapping free-text prose ('done (commit or PR), in progress, next and blocked') onto the status enum values. The `needs_you` and `bullets` fields remain unexplained in either place.

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

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

The description names a specific act on a specific artifact: telling collaborators a structured handoff (done/in progress/next/blocked). That is far more concrete than the sibling names alone (tell_people, send_message), but it never explicitly distinguishes itself from those siblings, so an agent must infer the boundary.

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

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

There is no statement of when to publish a handoff rather than call tell_people or send_message, and no stated prerequisites. The only constraint offered is 'No secrets.' The alternatives between `summary`+`details` and `body` are mentioned as format options, not usage conditions.

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 burden and does disclose meaningful behavior: 'it runs nothing there' (no remote execution side effect), that it returns id and seq, and that delivery is tracked via message_status on the joxo_more team. It stops short of permissions, rate limits, blocking vs async delivery, or failure behavior, so it is good 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?

Very compact and front-loaded, with no filler sentences. However the semicolon-packed phrasing ('delivery: message_status (joxo_more team)') reads as shorthand rather than clear prose, costing comprehension for its brevity.

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

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

No output schema exists and the description compensates by stating the return shape (id and seq) and how delivery is observed. For a 5-parameter, zero-required message tool, the essential calling information (payload options, reply targeting, return values) is present, so it is adequately 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 only 60%, so the description usefully clarifies the payload alternatives ('summary plus details, or body') and the in_reply_to semantics (an id or #seq), which the bare schema does not convey. It leaves target_device's interaction with the alternatives unstated, but it adds real meaning beyond the schema.

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

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

States a specific verb+resource (send an update or request) and names the recipients (collaborators or one target device), plus the key negative that it 'runs nothing there'. It does not, however, distinguish itself from siblings like tell_people or ask_people, which occupy very similar territory, so an agent cannot fully route between them from this text alone.

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 implied usage ('send an update or request', and how to answer with in_reply_to), which is enough context to attempt a call. But it never says when to prefer send_message over tell_people or ask_people, nor any exclusions or prerequisites, leaving the sibling choice 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 already declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the write/external-visibility profile is covered. The description usefully adds delivery context (people read it on their phones) and DM visibility semantics for to:"owner", but says nothing about persistence, editability, rate limits, or whether the whole team sees the post.

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 channel and payload form before the DM caveat; there is little filler. The phrase 'a heads-up' is slightly vague but costs almost nothing.

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

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

For a 6-parameter tool with a nested summary object and no output schema, the description covers the main composition paths but leaves thread/in_reply_to unexplained and does not indicate what posting returns or whether it is fire-and-forget. Adequate but with visible 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?

With 50% schema coverage, the description compensates partially: it explains that summary+details and text are alternative composition modes and what to:"owner" does. However, thread and in_reply_to are undocumented in both places, and the summary object's internal guidance lives in the schema rather than the description.

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 concrete verb and channel ('Post to the team chat people read on their phones') and specifies the payload shapes ('summary plus details, or text') plus the DM variant for to:"owner". An agent can tell it is a progress/notification poster, though it never names the nearby siblings send_message, ask_people, or publish_handoff to disambiguate.

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 rather than stated: it suggests reporting what you did with someone's idea, a result, or a heads-up, and clarifies that to:"owner" is a private DM. There is no explicit when-to-use-this-vs-send_message/ask_people/publish_handoff guidance, which matters given three plausibly overlapping messaging siblings.

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=false and openWorldHint=true; the description goes well beyond them by disclosing that the call blocks, that it honors a minutes budget with a default of 5, that the client may truncate the wait to under a minute, and that a null result arrives as changed:false with a re-check hint. These are the non-obvious traits an agent needs.

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

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

Two dense sentences plus a directive, front-loading the precondition before the mechanics and the prohibition. Every clause carries distinct information; nothing is 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?

An output schema exists, so return-shape documentation is not required, yet the description still summarizes the two possible outcomes (get_context-like data vs. changed:false). Combined with blocking semantics, defaults, and the client-truncation caveat, nothing needed to call this correctly is missing.

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

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

Schema description coverage is 0% for the single minutes parameter, so the description must carry the semantics — and it does, supplying the default (5) and the interaction rule that the client may cut the wait below that value. It does not restate the 1–10 bounds, which the schema already enforces.

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 blocking verb and its resource (holds until news from a teammate) and explicitly equates the successful return with get_context, which disambiguates it from that sibling without opening either schema. The purpose is unmistakable.

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

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

Gives an explicit precondition ("Only when you cannot go on without a teammate's answer") and an explicit anti-pattern ("Never use it to idle or poll"), plus the prescribed alternative behavior when idle ("end your turn"). This is textbook when/when-not guidance.

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