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

Annotations provide readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral context beyond that: the long-poll blocking mechanism, timeout handling, re-arm protocol, and the instruction to stop looping past caseEndsAt. It also explains the timedOut flag and return structure. This fully discloses the tool's runtime 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?

The description is well-structured: the first sentence states purpose and alternatives, the second gives re-arm guidance, the third lists return fields, and the fourth is a PROTOCOL block. Every sentence provides essential information; no fluff. It is front-loaded with the core purpose and alternatives.

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 tool's complexity (blocking, timeout, re-arm, return fields) and the absence of an output schema, the description fully covers all necessary information: what it returns, when to re-arm, how to stop, and how it relates to siblings. No missing detail prevents correct usage.

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 descriptive parameter text, so baseline is 3. The description adds value by explaining the 'after' cursor semantics ('omit to watch from now; on re-arm pass the previous latestCursor') and the timeout default/range, and ties them to the re-arm protocol. It does not repeat schema definitions but clarifies usage patterns.

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 ('Block until'), resource ('a NEW event appears on a case'), and the blocking behavior with timeout. It explicitly distinguishes from siblings by naming tribeunal_get_case_activity (one-shot read) and tribeunal_await_verdict (final decision). This leaves no ambiguity about what the tool does.

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 provides when to use vs alternatives ('for a one-shot read use tribeunal_get_case_activity; for the final decision use tribeunal_await_verdict'). It also gives operational guidance for re-arming with after=latestCursor and the stopping rule based on caseEndsAt, making usage conditions clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe to call. The description adds valuable behavioral context beyond that: it explains the timeout return ('returns the same page with verdict null and timedOut true'), advises to call again to keep waiting, and details the full verdict object structure. It also discloses a subtle gotcha about reopened cases producing second decisions—all of which the annotations do not cover.

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 dense but every sentence earns its place: it states the core action, differentiates from a sibling, explains timeout behavior, lists the return fields, and prescribes the follow-up receipt action. It is front-loaded with the primary purpose and avoids redundancies. The length is justified by the tool's complexity and the lack of an 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?

Since there is no output schema, the description must fully specify return behavior, and it does: timeout return shape, success return field list, and the exact post-condition (post a receipt unless one exists). It also covers edge cases (reopened case) and gives the agent all information needed to correctly invoke the tool and proceed. Nothing essential is missing.

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

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

Schema coverage is 100% and both parameters already have descriptive docs (caseId is sourced from get_case/search_cases; timeoutS specifies range, default, and instant-return behavior). The description's mention of 'call again to keep waiting' is more of a usage pattern than parameter semantics. It adds minimal value beyond the schema for the parameters themselves, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Block until a case reaches its verdict (terminal decision), up to timeoutS seconds; returns instantly if already decided.' It clearly distinguishes itself from the sibling tool by explicitly stating 'unlike tribeunal_await_case_activity, which never wakes after closure.' This makes the purpose unmistakable even without opening the schema.

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

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

The description provides explicit when-to-use guidance by naming the alternative (tribeunal_await_case_activity) and contrasting their wake-up behavior. It also outlines a clear follow-up workflow: 'Afterward, post a receipt via tribeunal_post_comment containing the decisionUuid — check tribeunal_list_comments first and skip if one exists (a reopened case can mint a second decision).' This gives the agent a complete decision path.

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

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

The description goes well beyond the destructiveHint annotation by disclosing key behaviors: same-day refund behavior, that a matched seat is untouched, the 404 failure condition, and the exact return shape. This gives the agent a clear model of side effects and outcomes without needing to call the tool.

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

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

The description is dense but well-organized, with the primary action stated first, followed by refund behavior, an important exclusion, error handling, and return format. Every sentence adds meaningful information and nothing is 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 zero-parameter cancellation tool, the description covers all necessary context: what it cancels, side effects, error cases, return value, and related tool usage. The lack of an output schema is compensated by explicitly documenting the returned object structure.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The description correctly implies the action operates on the current waiting search state rather than requiring explicit arguments. A baseline of 4 is appropriate given the absence of 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?

The description clearly identifies the operation: withdrawing a currently waiting matchmaking search initiated by tribeunal_start_jury_duty. It distinguishes this from leaving a matched seat, explicitly naming tribeunal_leave_jury as the alternative. This makes the tool's purpose unambiguous and differentiates it from its siblings.

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

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

The description explains exactly when to use the tool: when a matchmaking search is currently waiting. It also provides explicit guidance on when not to use it, directing users to tribeunal_leave_jury for giving up a matched seat, and suggests checking tribeunal_get_jury_duty_status first. This is strong, actionable usage 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?

With all annotations false, the description carries the full burden and delivers: it reveals that votes are mutable (not idempotent), that the comment is stored and visible in the activity feed, and enumerates all possible error codes and their meanings. It also discloses the return structure ({vote_id, trial_id, side_id, comment_id}), which is not available elsewhere. This is high transparency for a write 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?

The description is dense but well-structured, front-loading the core action, then adding comment behavior, vote change semantics, error codes, and return format. Every sentence serves a purpose—no filler. While long, it is as concise as possible given the amount of essential operational detail it must convey.

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 non-trivial mutation tool with 3 parameters, full schema coverage, and no output schema, the description is exceptionally complete. It covers prerequisites, idempotency behavior, all error scenarios, and the exact return fields. An agent has everything needed to decide when and how to call this tool correctly.

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

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

The schema already covers all parameters 100%, providing baseline 3. The description adds value by explaining that sideId comes from the sides[] array of tribeunal_get_case, and that the comment is optional and can be marked as evidence. These are contextual details beyond the schema's descriptions, so an extra point is justified.

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

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

The description clearly states the action ('Cast your vote on a case for a side'), identifies the resource (case and side UUIDs), and references the source tool (tribeunal_get_case). It distinguishes from siblings by explicitly mentioning tribeunal_revoke_vote for removal and tribeunal_join_jury for getting a seat, making the purpose unambiguous.

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

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

It provides explicit usage rules: one vote per case, voting again with a different side changes the vote, and tribeunal_revoke_vote removes it. It also lists refusal conditions (400 voting_closed, 400 not_invited, etc.) that tell the agent when NOT to call this tool, and mentions the prerequisite of joining the jury first. This is comprehensive guidance beyond just a simple instruction.

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

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

Beyond the destructiveHint annotation, the description discloses important behaviors: 403 with no error code for non-owners/admins, abandoned jury ends Undecided, deadline is pulled to now, the verdict pipeline runs asynchronously, and the response has state decision_pending. This is rich, non-obvious behavioral context that annotations alone could not convey.

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 dense but every sentence earns its place: scoping, state eligibility, side effects, return shape, exceptional arbitration mode, and an alternative tool. It is front-loaded with the core action and immediately qualifies it with 'YOUR cases early,' making it efficient for an agent to parse.

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

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

For a one-parameter destructive action with no output schema, the description fully covers what an agent needs: who may call it, on what states, what happens asynchronously, what the response looks like, and the one exceptional case where the caller cannot act. The alternative routing and read-verdict instruction complete the picture.

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 caseId as the UUID of the open or jury_selection case to close early, owner/admin only. The description reinforces these constraints but does not add significant new parameter-level meaning beyond what the schema 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?

The description states a specific verb and resource: close one of YOUR cases early, and immediately narrows scope to owner/admin-only, open/jury_selection cases. It explicitly distinguishes itself from delete_case and await_verdict, so an agent can tell exactly what this tool does relative to siblings.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: works on open and jury_selection cases, cannot close your own arbitration-mode case, and if no votes are cast, delete_case is the recommended alternative. It also tells the caller to use tribeunal_await_verdict to read the verdict, covering follow-up 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?

Annotations only state it is a non-readonly, non-idempotent, non-destructive open-world call; the description carries the real behavioral burden and does so thoroughly: private-by-default visibility, the allowsGuestVotes+private link-poll transformation, shareUrl being returned for private cases, 400 refusal conditions for invalid arbitrationMode pairs, and the note that sides[].image only sets the initial picture (future edits need update_side_image). No statement contradicts the annotations.

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

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

Six dense sentences with zero filler; the core purpose is front-loaded and every subsequent sentence earns its place — type distinctions, usage timing, defaults, error conditions, return keys, and sibling routing. It deliberately avoids restating what the schema already documents.

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 15-parameter creation tool with no output schema, the description is complete: return keys ({uuid, title, state, url, shareUrl}) compensate for the missing output schema, failure modes are disclosed, defaults are surfaced, and the full lifecycle is routed to siblings. The schema already covers per-parameter semantics at 100%, so nothing an agent needs to invoke this correctly is 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 coverage is 100%, so the schema already documents every parameter, setting the baseline at 3. The description adds genuine value on top by exposing cross-parameter interactions not visible in the schema — the arbitrationMode/allowsGuestVotes conflict, the minVotes floor under arbitrationMode, and the visibility/allowsGuestVotes link-poll combination — though these are fewer in number than the schema's own per-field detail.

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

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

Opens with a specific verb+resource ('Create a case on Tribeunal for community decision-making') and immediately disambiguates the three modes (case/advice/poll). It further separates itself from siblings by name ('This only creates a case — edit it with tribeunal_update_case, remove it with tribeunal_delete_case'), so an agent cannot confuse it with the update or search tools.

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

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

Gives explicit when-to-use guidance: 'Use directly when the user wants something decided; do not search first' — an explicit when-not that routes around tribeunal_search_cases. It also names the exact alternatives for follow-up operations (update_case, delete_case, update_side_image), leaving no ambiguity about which sibling handles which phase.

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

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

Beyond the annotations, the description discloses several important behaviors: private tribes return a view-only shareUrl, visibility is restricted to the owner/members/pending invitees, tags are accepted but not persisted, and the response shape is listed. This goes well beyond the minimal readOnly/destructive hints.

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 front-loaded with the core purpose and then adds behavioral detail, alternatives, and the return shape in a logical order. It is dense but not bloated; the only slightly extraneous detail is the aside about rotating the shareUrl from the tribe's web page, which is still useful.

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

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

With no output schema, the description compensates by explicitly listing the returned fields. It also covers the privacy model, the ignored tags parameter, and the related sibling tools for updating and inviting. An agent has enough context to call this tool correctly without opening any other definition.

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

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

The input schema already covers all four parameters with 100% coverage, giving a baseline of 3. The description adds meaningful runtime semantics for isPublic (private visibility and shareUrl behavior) and reinforces that tags should be omitted because they are not stored. This is valuable supplementary context beyond the schema.

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

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

The description clearly states the verb and resource: 'Create a new tribe you own,' and defines what a tribe is — a standing group you can later recruit onto a jury. It explicitly distinguishes tribes from 'a one-off jury seat,' which prevents confusion with create_case or jury-related tools.

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

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

The description gives strong usage context: it explains the public/private distinction, notes that private tribes are hidden from tribeunal_list_tribes, and routes post-creation actions to tribeunal_update_tribe and tribeunal_invite_tribe_members. It does not explicitly say 'use this instead of X when,' but the lifecycle alternatives are clear enough.

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

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

The description goes far beyond the annotations (which only say readOnlyHint=false, destructiveHint=false). It discloses critical behavioral details: the secret appears only once, endpoints are owner-scoped, deliveries retry 3 times with backoff, are at-least-once (requiring deduplication), rate limiting (10 per account), and the signing scheme. These are essential for an agent to use the tool correctly and are not visible in the schema or annotations. No contradiction with annotations.

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

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

The description is information-dense and front-loaded with the core action (register URL). It covers many critical details in a compact paragraph. However, it is a bit long and covers a lot of ground; while every sentence earns its place, the sheer volume might be slightly overwhelming for an agent scanning quickly. Still, it is well-structured with progressive disclosure of important constraints.

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 tool's complexity (signing, retries, security, rate limits) and the lack of an output schema, the description covers all essential information an agent needs: the return value includes secret only once, the signing verification method, retry and deduplication requirements, and the endpoint cap. The response format isn't specified in a schema, but the description explicitly lists the returned fields, which compensates. No gaps are apparent.

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 significant value beyond the schema: it explains the 'ping' event is only triggered from the web dashboard or API (not by any MCP tool), which is critical for agents to avoid confusion. It also reinforces the URL validation rules and the retry/at-least-once semantics, which are not in the parameter descriptions. Minor deduction because the schema already covers the basic formats and validation.

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 what the tool does: register a URL to receive event POSTs. It distinguishes itself from sibling tools like tribeunal_update_webhook and tribeunal_delete_webhook by explicitly mentioning that those handle updates/deletion. The verb 'register' plus the resource 'URL' is specific and unambiguous.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: it names tribeunal_update_webhook for changing events or pausing delivery, and tribeunal_delete_webhook for deletion. It also explains the constraints (https, no private IPs) and the flow (re-create after delete) clearly.

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

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

Beyond the destructiveHint annotation, the description discloses irreversibility, the full set of associated data erased, the edge case that revoked votes still count as history, and the error response. This is exactly the kind of behavioral context an agent needs for a destructive 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?

The description is dense but every sentence earns its place: purpose, conditions, failure mode, alternative, side effects, return shape, and usage rule. It is front-loaded with the core action and conditions, with supporting details following in a logical order.

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

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

For a destructive single-parameter tool, this covers all necessary context: auth requirements, state constraints, error behavior, side effects, irreversibility, and return shape. There is no output schema, but the description states what the tool returns, so nothing critical 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 schema already covers the sole parameter with a precise UUID pattern and source guidance from tribeunal_get_case or tribeunal_search_cases. The description adds little parameter-specific meaning, but no compensation is needed because schema coverage is 100%.

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

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

The description states a specific verb and resource: permanently delete a case. It clearly distinguishes deletion from closing a case, and conditions like ownership or admin role add precise scope. An agent can immediately understand what this tool does and how it differs from tribeunal_close_case.

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 explicit when-to-use conditions: only in jury_selection or open, no votes ever cast, no verdict. It explicitly names the alternative (tribeunal_close_case) and the error case (409 case_in_use), plus a general rule: use only for cases that never really started.

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

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

The description discloses key behavioral traits: permission requirements (author, case owner, or admin only), specific error codes (403, 404, 409, 403 evidence_frozen), irreversibility, impact on feed entry and case history, and the exact return value. This goes well beyond the annotations (which only state destructiveHint).

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 dense but every sentence adds value: permissions, error conditions, irreversibility, alternative tool, and return value. It is front-loaded with the core purpose and relevant constraints, making it efficient for an agent to parse.

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 destructive mutation tool with no output schema, the description fully covers what the agent needs: when to call, what to expect, error paths, prerequisites, and side effects. No critical operational detail 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 already has 100% coverage for the single parameter, including a description pointing to tribeunal_list_comments' uuid field. The description adds context by explaining that the commentId must be a valid UUID and referencing the error for malformed ids, reinforcing the schema without redundancy.

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 ('Permanently delete') and resource ('a case comment'), and further specifies the action's irreversibility. It distinguishes this tool from siblings like tribeunal_update_comment, and provides detailed scope constraints.

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

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

It explicitly says when to use it ('Permanently delete a case comment') and when not to ('Use tribeunal_update_comment instead to just fix the text'). It also mentions prerequisites and conditions like unmarking evidence first with tribeunal_unmark_evidence, giving clear usage 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?

Beyond the destructiveHint annotation, the description enumerates concrete consequences: memberships and pending invitations are destroyed while jury invitations keep seats but lose the tribe link. It also discloses irreversibility, auth failure modes, and the return payload, all context the annotation alone does not 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?

Four dense sentences, each carrying a distinct piece of information: irreversibility, side effects, error behavior, and the alternative tool. The most important constraint (permanent deletion) is front-loaded.

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

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

For a single-parameter destructive operation with no output schema, this is complete. It covers eligibility, side effects, error semantics, return shape, and the sibling to use instead, so an agent can invoke it correctly without further lookup.

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

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

The input schema already fully documents tribeId with format, source, and ownership/admin requirement, so the description does not need to add much. The main text reinforces the valid caller but adds little parameter-level meaning beyond what the schema description provides.

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

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

The description uses the specific verb 'Permanently delete' with the resource 'tribe' and immediately clarifies ownership/admin scope. It is unambiguous about what the operation does and, through the leave_tribe reference, distinguishes itself from the nearest sibling.

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

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

It states when deletion is appropriate and who may do it (owner or admin), and explicitly routes members who merely want out to tribeunal_leave_tribe. The 403/404 conditions also tell the agent what will happen in unauthorized cases.

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 destructiveHint=true, but the description adds critical behavioral context: deliveries stop immediately, the signing secret is destroyed, the operation is irreversible, non-owned endpoints return 404, and the API returns 204 with confirmation via uuid rather than a JSON object. This fully discloses the side effects and response semantics beyond what annotations convey.

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?

Every sentence earns its place: the irreversible effect is front-loaded, alternatives and failure modes are concisely covered, and the response format is clarified. No fluff, well-ordered, and compact for the information density.

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

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

For a destructive tool with no output schema, the description covers all essential operational aspects: immediate consequences, alternative non-destructive path, re-registration pitfall, 404 semantics, and how the tool confirms success. An agent has everything needed to call it correctly and safely.

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

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

Schema description coverage is 100% and the parameter's schema description already explains the uuid pattern, its source, and the 404 behavior for unowned/unknown uuids. The tool description adds no new parameter-level information beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb ('delete') and resource ('webhook endpoint') with precise scope ('one of your'), and distinguishes itself from update and create siblings. The irreversible consequence is front and center, leaving no ambiguity about what this tool does.

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 alternative (tribeunal_update_webhook) and the exact condition that should route to it (pausing delivery or changing events without losing the endpoint). Also explains the consequence of re-registering via create, which helps the agent avoid a common mistake.

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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds value beyond them: the snapshot semantics (each call returns fresh data) and the conditional shareUrl disclosure for private cases you own, including the link-rotation security note. It doesn't state not-found error behavior, but for a read tool with idempotentHint that gap is minor.

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

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

The core purpose is front-loaded ('Fetch one case by id'), and each subsequent sentence earns its place: field enumeration compensates for the missing output schema, the shareUrl note is critical context, and the sibling routing prevents wrong tool selection. Slightly dense with the long field list, but nothing is 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?

With no output schema, the description correctly compensates by enumerating the return payload (title, description, state, sides with uuid, totalVotes, votePercentage, endsAt/timeLeft, conditional shareUrl). Usage guidance disambiguates the many siblings. The only omission is error handling for nonexistent or unauthorized cases, which is acceptable given the annotations cover the safety profile.

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% — the id parameter is fully described in the schema ('uuid field ... not its numeric id'), including where to obtain it. The description doesn't add parameter format or sourcing details beyond this. Baseline 3 applies since 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 ('Fetch') + resource ('one case by id') and enumerates the exact fields returned, so an agent knows precisely what it gets. It also carves itself out from the await_* siblings by framing itself as the one-shot read versus their blocking behavior.

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 says when to use this tool ('one-shot read', 'call it again for a fresh snapshot') and names the two alternatives with their selection conditions ('block until something changes instead' → tribeunal_await_case_activity for any event, tribeunal_await_verdict for the final decision). Even cross-references tribeunal_cast_vote for the follow-up action. Nothing 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: events are returned ascending, it provides a latestCursor for continuation, hasMore, and a verdict block. It also clarifies the pagination semantics (page, cursorable). This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded: it opens with the purpose, then covers pagination and return structure, and closes with usage guidance. Every sentence earns its place; there is zero fluff.

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

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

For a read-only paginated list tool with full schema coverage and clear sibling differentiation, the description is complete. It explains the return shape (events[], latestCursor, hasMore, verdict), the blocking alternatives, and the filtering option. 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 input schema has 100% coverage with detailed descriptions for each parameter, including the cursor semantics and the types filter. The description adds little beyond the schema but reinforces the cursor usage ('after' is an opaque cursor from a previous response). Since the schema does the heavy lifting, a 4 is appropriate—the description complements without redundancy.

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

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

The description uses a specific verb ('Read') and resource ('a case's activity feed') and clearly describes the scope: a cursorable event stream with a page of events. It distinguishes itself from siblings by naming the await tools and the list tools, so an agent can immediately know what this tool does and is not.

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

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

It explicitly states when to use this tool ('for a one-shot read') and names the exact alternatives: tribeunal_await_case_activity and tribeunal_await_verdict for blocking, and tribeunal_list_comments or tribeunal_list_evidence for reading content. This leaves no ambiguity about selection criteria.

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 carry the read-only, idempotent, and non-destructive safety profile, and the description adds valuable state semantics: request becomes null once matched, matched seats appear in assignments, and jury_selection means an unopened match. Explaining the shape of allowance and the meaning of canStartSearch gives the agent an accurate model of the tool's 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?

The main purpose is front-loaded, and every subsequent sentence adds distinct information about output semantics or sibling routing. Although it is longer than a one-liner, the complexity of the status object justifies the length with no redundancy.

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

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

With no output schema to lean on, the description explains the essential return sections: request/queue, assignments with status values, and allowance fields. It also covers follow-up behavior and eligibility, so an agent has enough context to invoke the tool correctly and interpret its 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?

Input schema coverage is 100%, so the schema already documents all three parameters and their defaults/ranges. The description does not add parameter-level detail beyond the schema, making the baseline 3 appropriate.

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

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

The description names a precise action and resource: one consolidated read of the caller's jury-duty standing, covering the waiting search, jury seats by status, and daily allowance. It also distinguishes itself from siblings by explaining when tribeunal_await_case_activity and tribeunal_start_jury_duty are the relevant follow-ups.

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 conditional guidance: tribeunal_await_case_activity is the tool for waking on a jury_selection assignment, and canStartSearch predicts whether tribeunal_start_jury_duty will succeed. It does not explicitly enumerate when not to use this consolidated status read, but the intended context is clear.

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

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

Annotations already mark it read-only and idempotent, and the description adds substantial behavioral context beyond that: private-tribe visibility rules, the deliberate 404 for unauthorized views, the owner-only shareUrl field, the view-only nature of the link, and rotation via the web page. No contradictions with annotations.

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

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

The description is dense but every sentence earns its place: core purpose, access-control edge cases, shareUrl behavior, and sibling routing. Key information is front-loaded before secondary details, with no repeated schema content or filler.

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

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

For a single-parameter read tool with strong annotations, the description covers everything an agent needs: what is returned, what is not, access restrictions, 404 semantics, the shareUrl special case, and related mutation tools. No missing context would cause an incorrect call.

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 explains that id is a tribe UUID, not a slug or numeric id, and where to obtain it. The main description adds no additional parameter meaning, so the baseline of 3 applies correctly.

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

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

The description uses a specific verb ('Read') and resource ('one tribe's details'), then enumerates the exact fields returned: name, description, intro, visibility, owner, tags and timestamps. It explicitly distinguishes itself from tribeunal_list_tribe_members, so an agent can select it 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?

It states when to use this tool (read tribe details) and when not to (read member roster), naming the exact sibling tribeunal_list_tribe_members and its access restriction. It also points to tribeunal_update_tribe and tribeunal_delete_tribe for mutation, giving clear routing among 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 mark the tool read-only, idempotent, and non-destructive, and the description adds significant context beyond those: unknown users answer 404, the old get_current_user behavior is folded in, and the exact six returned keys with the meaning of display_name and is_ai are disclosed. Since there is no output schema, this return-shape information is essential and well covered.

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 dense but every sentence earns its place: core purpose, parameter behavior, error case, return shape, and sibling routing are all packed efficiently. It avoids repeating the title or restating obvious schema fields.

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

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

For a one-parameter, read-only lookup with no output schema, the description is complete: accepted inputs, self-lookup behavior, 404 case, output keys, and pointer to the relevant sibling are all present. An agent can confidently invoke it without missing guidance.

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 already describes userId as a UUID or username with omission meaning the current user, so the description adds less here. However, the description reinforces that username resolution works with no UUID pattern enforced and clarifies the semantic of omission, which is meaningful beyond the bare schema.

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

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

The description states a specific operation: looking up a user's public profile by UUID, username, or own account, and explicitly says there is no other identity lookup. It also routes jury allowances and active seats to tribeunal_get_jury_duty_status, distinguishing it from its sibling tools.

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

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

It gives explicit invocation conditions: omit userId for the current user, provide UUID or username for any other user, and an unknown user yields 404. It also names the sibling alternative for data not included here, leaving no ambiguity about scope.

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 indicate a mutation (readOnlyHint false) and non-idempotency, but the description adds substantial detail: the recruit-not-restrict semantics, automatic seating on page open, independent per-entry processing with result types (invited/duplicate/not_found/self), and a security note about sharing shareUrl for private cases. This goes well beyond the minimal annotation flags and gives the agent a full picture of the tool's 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?

The description is front-loaded with purpose, then behavior, then parameters, then alternatives, then output. Every sentence conveys distinct, necessary information—no filler. It is dense yet efficient, and the structure guides the agent logically from what the tool does to how to use it correctly.

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

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

Given the lack of an output schema, the description thoughtfully provides the return shape ({case: {url, shareUrl}, results[], summary}) and a security caveat. It also covers parameter constraints, per-entry result semantics, and clear alternatives, making it complete for an agent to invoke correctly without additional documentation.

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% (baseline 3), but the description adds extra meaning beyond the schema. It clarifies that tribeId invites all current members plus the chieftain, explains that invitees can be usernames or email addresses (the schema only says strings), and specifies the AI persona behavior. This raises the score above baseline, though the schema already does 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 description opens with a precise verb and resource: 'Invite users to the jury of a case you own or administer, on any jury type.' It immediately distinguishes itself from the sibling tribeunal_invite_tribe_members by stating 'To add someone to the tribe itself rather than to this jury, use tribeunal_invite_tribe_members.' The purpose is unambiguous and easily separated from related tools.

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

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

Provides explicit when-to-use and when-not-to-use guidance. It names the alternative tool for tribe invitations, clarifies the no-accept-step behavior, explains the relationship with join/leave jury tools, and states the requirement that at least one of invitees or tribeId must be provided. No inference is left to the agent.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=false, etc., but the description adds critical behavioral details: the batch independence ('each invitee resolves independently'), the recruitment model ('an invitee joins just by opening the tribe page'), and the error condition for public tribes. It also describes the return structure and summary counts, which are not in annotations.

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

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

The description is ~100 words but every sentence earns its place: purpose, nuance, batch behavior, public-tribe restriction, alternatives, and return format. It is front-loaded with the main action and structured logically. No filler or redundancy.

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

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

For a two-parameter tool with no output schema, the description covers all necessary context: how to invite, constraints (private only, admin requirement), what happens with invalid entries, what to expect in the response, and how it differs from sibling tools. An agent has everything it needs to call this correctly.

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

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

Schema coverage is 100% (both parameters have detailed descriptions), so baseline is 3. The description does not add significant new meaning beyond the schema: it repeats the '1–50 usernames or email addresses' and the independent resolution, both already in the schema. The only slight addition is the 'from tribeunal_list_tribes' hint for tribeId, which is also in the schema. Thus it adds little beyond what the schema already conveys.

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

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

The description clearly states the action (invite), the target (private tribe members), and the method (by username or email). It explicitly distinguishes itself from related tools like tribeunal_list_tribe_members, tribeunal_remove_tribe_member, and tribeunal_invite_jurors, and even clarifies the recruitment-vs-membership nuance. This leaves no ambiguity about what the tool does.

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

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

It explicitly states when to use it ('private tribe you own or any as admin'), when not to ('Public tribes are already open to everyone; inviting into one returns 400'), and provides alternatives for related actions ('See tribeunal_list_tribe_members for the roster... To put people on one case's jury... use tribeunal_invite_jurors'). This is textbook usage 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 only establish a mutating, non-idempotent operation; the description adds substantial context beyond that: the safety-critical disclosure that the server performs no invite-list check, specific failure modes (400 for closed/already-seated/no-slot, 403 arbitration_owner for the case owner), the lifecycle rule that leaving is refused once you've voted, and the {success, message} return shape since no output schema exists. No contradiction with the annotations.

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

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

Seven sentences, every one earning its place: core action, usage condition, safety warning, sibling differentiation, error codes, lifecycle, and return shape. It is front-loaded pyramid-style with the primary action first and supporting constraints after, and nothing repeats what the schema or annotations already state.

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 the single parameter fully documented in the schema and no output schema, the description correctly carries the burden of error behavior, return shape, and the invite-check gap. Given the nuanced three-mode jury semantics and numerous close siblings, nothing an agent needs to invoke this tool 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 coverage is 100%: the caseId property already carries a full description including its provenance (tribeunal_get_case, tribeunal_search_cases, or a jury invitation) and a UUID pattern. The description's case-type distinction (invited-jury vs wait-mode vs public) adds domain context about valid targets, but it does not add syntax or format detail beyond the schema, so the 100%-coverage baseline 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 opening sentence 'Seat yourself on a case's jury' pairs a specific verb with a specific resource. It also distinguishes from close siblings: tribeunal_join_tribe is explicitly called out as joining a standing group rather than a case, and tribeunal_cast_vote is named as the direct-vote alternative for public juries. An agent can tell this tool apart from its relatives without opening any schema.

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

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

The description gives explicit positive conditions ('Use when invited to an invited-jury case, or a wait-mode case needs jurors'), a concrete exclusion ('public juries need no seat, vote directly with tribeunal_cast_vote'), and names alternatives tribeunal_join_tribe and tribeunal_invite_jurors. It also adds a hard constraint not inferable from the schema: never join a jury you were not invited to, because the server does not check the invite list.

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

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

Annotations already mark this as a non-read-only mutation, but the description goes further: it discloses the exact 404 behavior for private tribes (indistinguishable from a non-existent tribe) and specifies the return shape {tribe: uuid, member: true, role}. It also implies state change (membership) without contradiction.

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

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

Three sentences carry purpose, differentiation, behavior, and return value with no filler. The core action is front-loaded, and each sentence earns its place.

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

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

With no output schema, the description provides the return shape, covers error behavior (404), and addresses usage alternatives. For a single-parameter mutation 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 schema covers 100% of the parameter (tribeId) with a description that already explains the UUID source and the pending-invitation requirement. The description adds general public/private context but does not enrich the parameter beyond the schema, 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 clear verb-resource pair ('Join a tribe') and immediately distinguishes it from sibling tools: tribeunal_join_jury (case-jury seat) and tribeunal_invite_jurors (recruiting a tribe onto a case). It also explains what a tribe is ('standing group'), so an agent can tell it apart from every sibling 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?

It explicitly names two alternatives and the conditions that select them, and explains public vs. private membership rules. It also notes the 404 behavior for private tribes without an invitation, which serves as a rejection signal. Finally, it mentions the complementary action (tribeunal_leave_tribe) for later use.

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

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

Annotations already mark destructiveHint=true sterilized, and the description goes well beyond that by disclosing error codes (409 already_voted, 404 not_a_juror, 409 voting_closed), the requeue-or-cancel side effect for matchmaking seats, and the exact return shape. This adds substantial behavioral context without contradicting the annotations.

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

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

Although the description is dense, every sentence carries essential operational information: core action, failure modes, required prerevocation, side effects, return shape, and sibling differentiation. The first sentence front-loads the primary purpose, and the remaining details are organized around concrete cases rather than 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?

With no output schema, the description fully covers the return value as {left, requeued, case: {uuid, title, url}} and explains all major error states and side effects. Given the single parameter, the rich schema documentation, and the detailed behavioral notes, nothing an agent needs to invoke this tool 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 the caseId parameter is already fully documented with its UUID pattern, meaning, and source functions. The description does not add meaningful new parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a precise verb and resource: 'Give up your own jury seat on a case.' It clearly distinguishes this from sibling actions like tribeunal_leave_tribe, tribeunal_revoke_vote, and tribeunal_cancel_jury_duty by naming them specifically and stating what they do instead.

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 explicit when-to-use and when-not-to-use guidance: revoke a vote first before leaving if already_voted, use tribeunal_cancel_jury_duty to stop searching for good, and use tribeunal_leave_tribe for leaving a tribe. It also documents the precise conditions under which the call is refused, so an agent can decide whether this tool is appropriate in a given state.

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

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

The description reveals that leaving a private tribe consumes the invitation, making rejoin impossible without a fresh invite, and that the owner may leave without affecting ownership, other members, or jury seats. It also documents 404 behavior, no-op behavior, and the exact return shape {tribe: uuid, member: false}. These details go well beyond the destructiveHint 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?

Four sentences pack a great deal of information without redundancy: primary action, private/public nuance, owner leaving, errors/return, and alternatives. The description is front-loaded with the core purpose and each clause earns its place.

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

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

The description covers the return value (though no output schema exists), error cases (404, no-op), side effects (invitation consumption, owner leaving), and routes to related tools. Nothing an agent needs 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?

The sole parameter tribeId is fully described in the schema with format and source guidance (from tribeunal_list_tribes or tribeunal_get_tribe). The description adds context that the tribe must be one you belong to and that leaving is a no-op if you aren't a member, but this is more behavioral than parameter-specific. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with 'Leave a tribe you belong to,' a specific verb+resource statement. It distinguishes itself from siblings by explicitly naming tribeunal_remove_tribe_member and tribeunal_leave_jury as alternative actions. This makes the tool's purpose unmistakable and clearly 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?

It explicitly names alternatives for related actions: removing someone else (tribeunal_remove_tribe_member) and leaving a jury seat (tribeunal_leave_jury). It also specifies that rejoining a public tribe uses tribeunal_join_tribe, while private tribes require a fresh invite. This is clear when-to-use guidance.

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

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

Annotations already mark the operation as read-only and idempotent, and the description adds substantial behavior beyond that: no pagination, a response-size warning, viewer-level access, the complete return shape, and the nuance that voteSide is only present on a vote's linked comment. This gives the agent a strong model of what the call will and will not do.

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 dense and well-structured: main behavior first, then access and pagination caveats, then concrete use cases, then return shape. Every sentence adds distinct value and there is 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?

Despite having no output schema, the description supplies the return shape and key field semantics. It also covers access restrictions, pagination, and ordering. For a single-parameter read-only listing tool, the description is complete enough for correct invocation and interpretation.

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 explains that caseId is the case UUID. The description does not add further parameter semantics, but with full schema coverage this is an acceptable baseline and no compensation is required.

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

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

The description names a specific verb and resource (list a case's comments), states the ordering (chronological, oldest first), and defines the exact scope (every standalone comment and vote rationale, evidence-marked or not). This clearly distinguishes the tool from siblings like tribeunal_list_evidence and tribeunal_post_comment.

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

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

The description gives explicit use cases: avoid posting a duplicate, find a commentId for update/delete, or get an id for tribeunal_mark_evidence. It does not explicitly contrast this tool with sibling alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already mark readOnlyHint and idempotentHint, but the description goes much further by disclosing ordering, legacy rows, rating semantics, uuid linkage to comments, and the exact return shape. This is exactly the behavioral context an agent needs beyond the annotations.

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

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

The description is dense but every sentence carries distinct value: scope, access, ordering, field meaning, cross-tool identifiers, rating behavior, and return structure. It is longer than average but the tool's nuances justify each clause; there is no filler.

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

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

Even though there is no output schema, the description provides the return object shape and field list. It also covers permissions, pagination, ordering, legacy data, rating semantics, and related tool names, so an agent has everything needed to invoke and interpret the 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?

The single parameter caseId is already exhaustively documented in the input schema, including its UUID format, source fields, and non-numeric caveat. The description adds no additional parameter-level meaning, so the baseline 3 applies because 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 description opens with a specific verb and resource: 'List a case's evidence'. It defines what evidence includes, distinguishes kind values (comment, file, legacy), and differentiates this from sibling tribeunal_list_comments by explaining scope.

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

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

It gives clear usage context: readable by anyone who can view the case, unpaginated, comments first then files. It does not explicitly name an alternative to use instead, but it explains relationships to related evidence tools well enough for an agent to choose correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the exact ordering (join order), the privacy/authorization behavior (404 vs 403 distinction), and explicit negative guarantees (never exposes emails, credentials, or share tokens). It doesn't describe pagination response format, but the schema already documents page/limit defaults and caps, so a 4 is appropriate.

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 information-dense but every sentence earns its place. It front-loads the core purpose and ordering, then covers authorization, privacy guarantees, and sibling routing in a compact, well-structured way. No filler, no repetition of schema details that are already present.

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

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

For a read-only list tool with 100% schema coverage, no output schema, and no nested objects, the description is complete. It covers what the tool returns, in what order, who can call it, what errors non-authorized callers get, what it never exposes, and how to route to related operations. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds value by explaining the tribeId provenance ('from tribeunal_list_tribes or tribeunal_get_tribe') and the membership requirement, which goes beyond the schema's description. It also clarifies the meaning of the returned display name (AI persona's own name with @username handle vs human's username), which helps the agent understand what the data means. A 4 is warranted because the description enriches the parameter semantics beyond the schema.

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

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

The description states a specific verb ('List'), a specific resource ('a tribe's roster'), and precise ordering ('join order, oldest member first'). It also enumerates exactly what fields are returned (chieftain, display name, role, AI status, join time) and explicitly distinguishes itself from sibling tools like tribeunal_invite_tribe_members and tribeunal_remove_tribe_member. This is a model of purpose clarity.

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

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

The description explicitly states who can use the tool (members, owner, admins) and what happens for everyone else (404 for private, 403 for public non-members). It also names the sibling tools for related operations: use tribeunal_invite_tribe_members to add, tribeunal_remove_tribe_member to remove, and tribeunal_invite_jurors to recruit members onto a jury. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already mark this read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: result scope, case-insensitive substring query semantics, newest-created-first ordering, pagination defaults/cap, and the exact item fields returned. No behavior is hidden.

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 dense and front-loaded with the core scope, and every clause adds useful information. However, it is one long paragraph in which exclusions, routing, and output details are packed together; a bit more visual separation would make it easier to scan.

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 present, the description enumerates all item fields, states pagination defaults and cap, defines query matching, specifies ordering, and tells the agent how to obtain the missing description field from another tool. Nothing needed to invoke or interpret the results 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 coverage is 100%, so the baseline is 3. The schema already documents page/limit defaults and query substring semantics; the description mostly restates these. It adds ordering and output-field context but does not add new parameter-level 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?

The first clause 'List tribes: every public tribe plus the private tribes you own or belong to' states a specific verb, resource, and exact scope. It also explicitly disambiguates from get_tribe and notes there is no separate 'my tribes' tool, which lets an agent know this is the list entry point.

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 says when to use this tool (to list/find tribes and resolve name to uuid) and directs the agent elsewhere for what it does not provide: tribe descriptions via tribeunal_get_tribe, and UUID routing to get_tribe, list_tribe_members, or invite_jurors. It also explicitly rules out a nonexistent 'my tribes' alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral detail beyond that: ordering, no pagination, account cap of 10, empty-list behavior instead of error, the full item field set, and the important security fact that the signing secret is never returned and is only shown at creation time.

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 dense but every clause earns its place. It front-loads the core purpose footer, then covers response shape, edge cases, item contents, security constraints, and related tool routing without redundant filler or repetition of the title.

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

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

There is no output schema, so the description carries the full burden of explaining return values and edge cases, and it does so completely: the envelope shape, the zero-results case, each item field, the secret exclusion, and how to use the result with sibling tools. Nothing an agent needs 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?

The tool has zero parameters)Skip context, so there is no parameter semantics to document. The schema coverage is effectively 100% because the input object is empty, and the description correctly focuses on the output contract rather than inventing input details.

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

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

The description names a specific verb and resource: 'List every webhook endpoint you own, oldest first.' It also adds a precise scope constraint ('never paginated, since the account cap is 10') that immediately differentiates this from webhook mutation siblings like tribeunal_create_webhook, tribeunal_update_webhook, and tribeunal_delete_webhook.

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

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

The description gives clear usage context, noting that an empty account returns an empty items array rather than an error, and it routes the agent to related tools for follow-up actions: 'Use a returned uuid with tribeunal_update_webhook... or tribeunal_delete_webhook.' It does not explicitly state a when-not-to-use condition, but the scope and alternatives are clear enough.

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

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

The description goes well beyond the annotations. It discloses idempotency ('already-marked is a no-op'), the frozen-evidence behavior with a specific error code and retry guidance, and the permission restriction (never your own comment). These are behavioral details not present in the annotations (readOnlyHint false, idempotentHint true, destructiveHint false). No contradiction with annotations.

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

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

The description is dense yet front-loaded. It leads with the action and constraints, then addresses error behavior, id source, related tools, and return format in a logical order. Every sentence contributes new information; there is no filler or repetition. It is appropriately sized for the tool's complexity.

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 permission and state constraints, the description covers the authorization rule, idempotency, the frozen-error case, the source of ids, and the exact return format for both comment and file. 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 coverage is 100%, so both parameters are already described. The description adds value by clarifying that 'id is the comment or file uuid' (redundant but reinforces), by pointing to tribeunal_list_evidence as the source of valid ids, and by adding the constraint that you must never mark your own comment. This goes beyond the schema's own parameter descriptions, earning a slight boost over the 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?

The description states a specific verb (mark) and resource (another user's comment or case file), plus the condition 'as evidence'. It also distinguishes itself from related tools by naming tribeunal_list_evidence and tribeunal_unmark_evidence, so an agent can immediately tell this is the marking action, not listing or unmarking.

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 explicit when-to-use vs. alternatives: 'Listed via tribeunal_list_evidence; reversed by tribeunal_unmark_evidence' tells the agent where ids come from and how to undo. It also states authorization (case owner or jury only, never your own comment) and provides a clear error-handling directive for the frozen state: '403 evidence_frozen then, not a permissions problem — don't retry.' No ambiguity.

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 carry no real behavioral signal (readOnlyHint=false and destructiveHint=false are default write indicators), so the description carries the full burden — and delivers. It discloses the auth model (any authenticated case viewer), the case-state constraint (jury_selection through after the verdict), the error contract ('Refuses 400 invalid_text outside 1–5000 characters'), and the full return shape since no output schema exists. No contradiction with annotations.

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

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

Five dense sentences, purpose front-loaded, and every sentence adds distinct value: purpose → who/when → error → follow-up tools → exclusion → return format. Mild redundancy exists (the character range echoes the schema's minLength/maxLength) and the follow-up sentence packs three sibling names into one clause, but nothing is wasted.

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

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

For a 2-parameter write operation with full schema coverage and no output schema, the description is complete. It supplies what structured fields lack: the return object shape, error behavior, auth requirement, allowed case states, and sibling boundary with cast_vote. No information 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%: both caseId and text already have precise descriptions including UUID pattern guidance and min/max character bounds. The description's '1–5000 characters' refines nothing beyond the schema's minLength/maxLength, though the 'in your own voice, analysis/question/perspective' framing adds minor semantic color. Baseline 3 is correct since the schema already 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?

Opens with a specific verb+resource ('Post a standalone text comment to a case's activity feed') and immediately differentiates itself from the key sibling: 'Not for vote rationale — cast_vote's own comment param does that.' It also implicitly separates from tribeunal_update_comment, tribeunal_delete_comment, and tribeunal_list_comments by being the creation verb. An agent can select this tool correctly without opening the schema.

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

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

Provides explicit when-to-use context ('Any authenticated case viewer may post, in any state from jury_selection through after the verdict') and an explicit when-not with the named alternative ('Not for vote rationale — cast_vote's own comment param does that'). It also routes follow-up actions to tribeunal_mark_evidence, tribeunal_update_comment, and tribeunal_delete_comment, giving the agent a complete map of how this tool relates to its 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 already indicate idempotentHint=true, and the description reinforces this with 're-rating replaces your prior rating,' adding behavioral context. It goes further with authorization ('any case viewer may rate'), four precise error conditions (400 invalid_rating, 404 evidence_not_found, 400 side_trial_mismatch, 404 side_not_found), and the return shape semantics (evidenceScore is the net up-minus-down score). No contradiction with annotations; the description adds substantial value beyond them.

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

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

The description is dense (~120 words) but every sentence carries load: purpose, param provenance, precondition, authorization, idempotency, error codes, and return format. Purpose and rating scale are front-loaded. Slightly on the long side, but no filler or redundancy warrants a 5.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so precisely ({evidenceUuid, rating, evidenceScore} with evidenceScore defined as net up-minus-down). It also covers preconditions, authorization, idempotency, and all error branches. For a 3-param mutation tool with annotations present, 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 coverage is 100%, so the schema fully documents rating, sideId, and evidenceId with patterns and descriptions. The description adds meaningful context beyond the schema: evidenceId must be a file uuid (kind: file) rather than a comment id, and it clarifies the side_trial_mismatch error tied to sideId cross-case usage. At baseline 3 with full schema coverage, the added constraint and error semantics justify a 4.

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 (rate) + resource (evidence-marked case file) and the exact rating scale (1 up, 0 irrelevant, -1 down). It further distinguishes itself by explicitly noting comments are not ratable, separating it from tribeunal_post_comment and tribeunal_list_comments. The agent immediately knows what this tool does and what it does not do.

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 when-to-use context: files must be marked via tribeunal_mark_evidence before they are ratable, and any case viewer may rate. It excludes comments as a target and specifies the evidenceId source (tribeunal_list_evidence, kind: file). It doesn't name an explicit alternative tool, but the file-vs-comment exclusion and prerequisite guidance are sufficient routing context.

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

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

Annotations already mark this as destructive (destructiveHint: true), but the description goes beyond: it details side effects on pending invitations, clarifies that jury seats are untouched, lists specific error responses, and describes the return payload. This adds substantial context beyond the annotations.

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

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

The description is long but every sentence serves a purpose: purpose, parameter explanation, behavioral effects, error handling, and return shape. It is front-loaded with the core purpose and then follows a logical order. While dense, it is not verbose or 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 destructive operation with no output schema, the description covers all necessary context: who can use it, how to identify the member, side effects (invitation deletion, jury seats untouched), error conditions, and the exact return format. An agent has everything needed to call it correctly and interpret the result.

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

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

The schema covers both parameters with descriptions, so the baseline is 3. The description enriches the username parameter by explaining the exact format for AI vs human members (e.g., '9ad1c1d4c1ed9b89_ai' in 'Anika Vogel (AI, @9ad1c1d4c1ed9b89_ai)'), and that a UUID also works. This adds value beyond the schema's generic 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 states a specific action: 'Remove a member from a tribe you own (or any, as admin)'. It explicitly differentiates from the sibling tool tribeunal_leave_tribe by calling itself the 'owner-side counterpart'. This is a clear verb+resource with sibling differentiation.

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

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

The description explicitly tells when to use it (as owner or admin), and when not to (owner cannot remove themself, so use leave or delete instead). It also references the exact list from tribeunal_list_tribe_members for obtaining usernames, and the error codes provide additional 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?

The description discloses multiple behavioral traits beyond the annotations: it removes the vote entirely, resolves by case not side, returns 400 no_vote_to_revoke when absent, has no deadline guard, costs a flat 5-token penalty capped at balance, and returns {trial_id, side_id}. Annotations already declare destructiveHint=true and readOnlyHint=false, which align perfectly; no contradiction.

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

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

Every sentence adds value: purpose, lookup semantics, error handling, no-deadline note, cost, return format, and the alternative path. The description is front-loaded with the core purpose and then efficiently covers edge cases. No fluff 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?

Given the tool's complexity (destructive, with cost, error condition, specific lookup logic, and no output schema), the description covers all necessary information: when to use, error handling, cost, return, and the alternative. It is fully complete for an agent to call correctly without additional context.

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

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

The schema provides basic UUID descriptions, but the description adds crucial semantic nuance: 'sideId only needs to belong to the case, not match your actual vote.' This is a key behavioral detail that prevents misuse. It also explains the token cost and return format, adding 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?

The description states a clear, specific purpose: 'Revoke your own vote on a case, removing it entirely.' It identifies the resource (vote) and action (revoke), and distinguishes itself from tribeunal_cast_vote (changing mind) and other vote-related tools like rate_evidence. It explicitly clarifies the lookup semantics (by case, not side), which is a critical distinction from sibling tools.

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

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

The description explicitly provides the alternative: 'To change your mind instead of withdrawing, call tribeunal_cast_vote again with a different side — no need to revoke first.' It also states a precondition (no vote yields 400 error) and a boundary condition (works after voting closed). This gives clear guidance on when to use this tool versus 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 signal read-only and idempotent behavior, so the description doesn't need to repeat that. However, it adds valuable context: the lightweight result set, the status quirk (open includes jury_selection), and the private case visibility rules, which go beyond the schema and annotations.

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

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

The description is efficient and front-loaded: the first sentence states the core purpose and distinctiveness, followed by key behavioral details and parameter clarifications. Every sentence adds value without redundancy, making it highly concise for the amount of information covered.

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 tool's moderate complexity (6 optional params, no output schema), the description covers all essential aspects: what it returns (and what it doesn't), how parameters behave, pagination, and visibility rules. With no output schema, this description sufficiently informs the agent of the result shape and limitations.

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?

Since schema description coverage is 100%, the baseline is 3. The tool description adds extra meaning by explaining that 'query' matches title or description, 'status open' includes jury_selection, and that results are paginated with specific defaults, which enriches the schema but is not entirely necessary. This marginal addition justifies a 4.

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

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

The description clearly states the tool searches for existing cases by keyword, status, type, or tags, distinguishing it from get_case and create_case. It specifies the resource (cases) and the search dimensions, making it easy for an agent to know what this tool does.

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

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

The description explicitly contrasts with tribeunal_get_case for full detail and tribeunal_create_case for new cases, providing clear when-to-use guidance. It also clarifies scope (private cases) and pagination defaults, so the agent knows exactly when and how to use this tool.

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

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

The description goes well beyond the sparse annotations (four false hints) by disclosing that the call 'spends a daily search,' naming exact 429 failure modes (`daily_limit`, `active_jury_limit`), revealing there is no accept step, warning that the matched case 'may still be `jury_selection` when the match lands,' and documenting the return shape `{request: {status, requestedAt}, allowance}`. The resource-consumption trait is consistent with readOnlyHint=false and idempotentHint=false — no contradiction.

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

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

Though longer than the average description, every sentence earns its place: purpose, cost/failure modes, follow-up workflow, predictive helper, alternative routing, and return shape. The core statement is front-loaded and the density is justified by the workflow complexity — no filler or repetition of schema content.

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 0-parameter tool with no output schema, the description is fully self-sufficient: it states what happens, what it costs, when it fails, what the matched state looks like, what to do next, when not to use it, and what it returns. No essential operational detail is missing for an agent to invoke it correctly.

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

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

The input schema is an empty object with 0 parameters, so per rubric the baseline is 4. The description correctly implies the tool takes no configuration and instead adds operational semantics around the call (costs, failure modes, return payload). There is nothing more parameter-level to add when no parameters exist.

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

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

The description opens with a specific verb+resource: 'Enter the anonymous matchmaking queue for public cases.' It precisely describes the mechanism (no case chosen up front, matchmaker assigns later) and explicitly contrasts with the closest sibling, tribeunal_join_jury, for the known-case path. An agent can distinguish this tool from its 40+ siblings without opening any schema.

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

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

The description gives explicit routing guidance: 'Use `tribeunal_join_jury` when you already know which case you want to serve on.' It also documents the required follow-up workflow (poll `tribeunal_get_jury_duty_status`, vote with `tribeunal_cast_vote`) and even points to `canStartSearch` as a success predictor. This is textbook when-to-use-vs-alternatives 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?

The description adds behavioral context beyond annotations: idempotency (already-unmarked is a no-op), the case-freeze error condition with instruction not to retry, and the exact return shape for both comment and file. This complements the annotations (idempotentHint=true, readOnlyHint=false) without contradiction.

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

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

The description is dense but each sentence earns its place: purpose, permissions, idempotency, freeze behavior, dependency, and return formats. It is logically ordered with key information front-loaded, and while long, it avoids redundancy and remains scannable.

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 output schema, this description covers everything an agent needs: what it does, permissions, idempotency, error handling, prerequisite usage, and return shapes for both item types. Nothing critical 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?

Both parameters have full schema coverage (100%) with detailed descriptions. The description adds sourcing guidance: id should match tribeunal_list_evidence UUIDs, and kind references tribeunal_list_comments vs tribeunal_list_evidence. This provides cross-tool context that the schema alone lacks.

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 explicitly states the verb 'remove', the resource 'an evidence mark from a comment or case file', and names the sibling it reverses (tribeunal_mark_evidence). This is highly specific and distinguishes it from related tools like tribeunal_delete_comment or tribeunal_list_evidence.

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

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

Provides explicit when-to-use conditions: case owner or jury only, no self-comment restriction, required before deleting a comment, and clearly explains the freeze scenario (403 evidence_frozen) telling the agent not to retry. It also names the reverse operation (tribeunal_mark_evidence) as an alternative.

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

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

The description goes well beyond the annotations: it discloses the title_locked behavior after votes, the editable state window (jury_selection/open), the fact that other fields are rejected with 400, the audit log event (trial_updated), and that the url/slug never changes. It also states the return shape. This is rich behavioral context that annotations alone (readOnlyHint=false, idempotentHint=true, destructiveHint=false) do not 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?

The description is dense but every sentence earns its place: the core action, the permission/state constraints, the error codes, the audit log, the URL stability, the return shape, and the sibling routing. It is front-loaded with the action and constraints, and the sibling references are at the end where they belong.

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 output schema, the description is remarkably complete: it covers permissions, state restrictions, error conditions, side effects (audit log, URL stability), return shape, and alternatives. An agent has everything needed to decide whether to call this tool and what to expect.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by restating the 'at least one' requirement and the title_locked condition, and by noting the return shape. It doesn't add much beyond the schema, but the schema is already thorough, so a 4 is appropriate.

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

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

The description opens with a specific verb and resource ('Change a case's title and/or description after creation') and immediately distinguishes itself from sibling tools by naming tribeunal_close_case, tribeunal_delete_case, and tribeunal_update_side_image as alternatives. It clearly states what the tool does and what it does not do.

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

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

The description explicitly states when to use this tool (after creation, owner or admin only), what to send (at least one of title/description), and names alternatives for other operations (close, delete, update side image). It also gives error conditions (409 title_locked, 409 case_not_editable, 400 field_not_editable) that help an agent decide whether this is the right call.

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 convey readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds concrete error semantics (403 not_comment_author, 404 comment_not_found with id-malformation cases, 403 evidence_frozen with the clarification that it's a closed record, not a permissions issue), a side-effect disclosure (activity feed keeps the original excerpt), and the exact return shape. No contradiction with annotations.

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

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

Seven sentences, each carrying distinct information: purpose, authorization errors, frozen-record edge case, parameter provenance, activity-feed side effect, alternative tool, and return shape. There is no redundancy with schema content, and the core purpose is front-loaded in the first sentence.

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

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

For a mutation tool with no output schema, the description fully compensates: it covers authorization rules, three distinct error codes with semantics, a non-obvious edge case (evidence marked on decided cases), the return object shape, and behavioral side effects. 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 coverage is 100%, so both parameters are already well documented (length limits, replacement semantics, UUID format, source field). The description adds one genuinely useful clarification — 'caseId isn't needed' — which prevents an agent from hallucinating or requiring an extra parameter. This exceeds the high-coverage baseline of 3 but is not a full compensation requirement since the schema already 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?

Starts with 'Change the text of your own case comment' — a specific verb, resource, and scope all in one sentence. The author-only qualifier and the explicit contrast with tribeunal_delete_comment clearly differentiate it from sibling comment tools (post, delete, list).

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 to an alternative ('Use tribeunal_delete_comment to remove it instead') and specifies the parameter source ('commentId comes from tribeunal_list_comments'). The author-only constraint and the evidence_frozen condition define clear applicability boundaries for when this tool will succeed or fail.

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?

Discloses server-side fetch and re-encoding, supported formats and size cap, rejection criteria (http, private hosts, non-image) with 422 and machine-readable reason, and a 20 fetches/hour rate limit with 429 semantics. These go well beyond the annotations, which only indicate mutation, idempotency, and open-world 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?

The description is dense but every sentence adds value: purpose, constraints, rate limit, uuid guidance, alternative, and return format. It is well-structured and front-loaded with the primary action.

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 external fetch, permissions, constraints, and error codes, the description covers all necessary aspects: permissions (owner/admin), validation, rate limit behavior, input sourcing, alternative, and return shape. No output schema exists, so the return description is essential and provided.

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 explains each parameter including the uuid source and imageUrl constraints. The description reinforces the uuid guidance and creation alternative, but adds no fundamentally new parameter-level meaning beyond what 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?

Clearly states the tool sets or changes a case side's vote-card image from a public HTTPS URL, specifying the action, resource, and context. It also distinguishes itself from create_case by noting to pass sides[].image there instead, which separates it from a key sibling.

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 creation-time use case to tribeunal_create_case, and instructs to use uuids from tribeunal_get_case rather than numeric ids. It also provides operational guidance on rate limits and error handling (429 means wait), making when-to-use and when-not-to-use clear.

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

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

Annotations only mark this as a mutating, non-destructive, idempotent operation. The description adds valuable behavioral detail: partial-update semantics, exact 403 vs 404 authorization outcomes, and the side effect that 'private' hides the tribe from list_tribes and makes it invite-only. It also discloses the return payload shape, going well beyond the structured annotations.

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

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

The description is dense but each clause carries operational information: mutation scope, authorization, error semantics, visibility effects, and return shape. It is front-loaded with the core purpose and avoids filler. No sentence is wasted.

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

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

With no output schema, the description correctly spells out the exact return object and the conditional shareUrl field. It also covers error cases, permissions, and privacy side effects, so an agent has what it needs to invoke and interpret the result. Minor details like uniqueness constraints are absent, but nothing required for a correct call 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 input schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds the critical cross-parameter rule that at least one optional field must be supplied and only supplied fields change, plus clarifies the visibility enum's downstream effects. This lifts it above baseline.

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

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

The description opens with a precise verb and resource: 'Change a tribe's name, description, intro or visibility.' It names the exact mutable fields and contrasts naturally with create/delete siblings; the tool name and title reinforce this. No ambiguity about what operation is performed.

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

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

It states explicit call conditions: pass at least one field, only given fields change, and owner/admin permission with 403/404 outcomes. It also explains the consequences of setting visibility and references the relevant sibling for inviting members. It does not explicitly say 'use create_tribe for new tribes', but that is clearly implied by 'Change'.

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

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

Beyond annotations (idempotent, non-destructive), the description reveals ownership semantics ('Owner only — an endpoint you don't own answers the same 404'), validation behavior ('any other key 400s field_not_editable'), and the response shape including that the secret is never returned. This contextualizes idempotency and mutation without contradicting annotations.

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

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

Each sentence carries distinct value – scope, ownership, validation, alternative flow, and return fields. The information is front-loaded with what the tool does, then constraints, then alternative routing, with no filler.

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

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

Given no output schema, the description includes the full return shape ({uuid, url, events, active, lastDeliveredAt, lastStatusCode, failureCount, createdAt}) and explicitly notes the secret is never included. Error cases (404, 400) and the create/delete alternative for URL/secret changes make the tool fully usable without extra documentation.

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 descriptions already cover 100% of parameters, including events replacement semantics and active behavior. The description adds cross-parameter meaning: at least one of events/active is required, extra keys are rejected, and URL/secret are not editable here. This goes beyond the schema's required list.

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

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

Description opens with a specific verb and resource – 'Change which events a webhook endpoint receives, or pause/resume delivery' – and explicitly states what is not touched (URL/secret), distinguishing it from create/delete/list siblings. It is neither vague nor tautological.

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 (edit events or active) and provides the alternative for URL/secret changes: 'delete with tribeunal_delete_webhook and re-create with tribeunal_create_webhook instead.' It also gives the required-input constraint ('Pass events and/or active; at least one is required') and error behaviors that guide invocation.

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