Veyrul media knowledge hub

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

Annotations already cover mutability and idempotency, yet the description adds real value: participant-only scope, the reason being private, an audited owner resolution path, the requirement for an agent credential, and the explicit note that outcome credit never changes permissions. These disclosures go beyond structured fields, though the actual appeal workflow outcome remains unstated.

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

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

Three short sentences with no padding, but the opening sentence spends the most prominent position on jargon ('audited owner resolution') instead of the action being performed. Length is fine; front-loading is poor.

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, nested parameters, and 0% schema description coverage, the description omits what an appeal actually does to the outcome, whether it can be repeated, and what a caller receives. The credential and idempotency notes help but do not fill the gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and largely does not. It names idempotency_key only as a requirement, and 'private reason' faintly gestures at the appeal.reason field, but the out_... ID format and the reason's 2000-char constraint are left entirely to 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 leads with the opaque phrase 'Participant-only private reason for audited owner resolution' rather than stating a clear verb+resource. Only the title ('Appeal an outcome decision') tells an agent this submits an appeal, and the description never names it relative to siblings like review_outcome, submit_outcome, or get_outcome.

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?

Nothing says when to use this versus review_outcome, submit_outcome, or get_outcome, and no prerequisites beyond a credential mention. The caveat 'An appeal does not automatically award points' is a useful expectation-setter but is not routing guidance.

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

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

Goes well beyond the annotations by naming exactly what survives the cancellation: existing messages, private membership, receipts and consumed funds — which substantiates the destructiveHint=false / idempotentHint=true profile rather than merely restating it. It also declares the required write scopes and the idempotency_key obligation, so an agent understands both blast radius and prerequisites.

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

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

Three tight sentences with the primary effect front-loaded, then preservation semantics, then the alternative and preconditions. Dense but every clause carries information; no filler.

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

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

For a 3-param mutation with no output schema, the description covers safety-relevant behaviour, auth scopes and idempotency well. The remaining gap is the idempotency/retry semantics of an already-cancelled thread and any hint about what the call returns, plus the unexplained reason field.

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 only 33%, so the description should compensate, and it does not: thread_id and the nested input.reason (a required free-text justification, 1-500 chars) are never explained. The one parameter it does mention, idempotency_key, is already fully documented in the schema, so the description adds almost nothing beyond structured fields.

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

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

Concrete verb + resource: stops new assistance/publication and cancels pending bound resident requests, which is far more informative than a tautology of the title. It does not clearly separate itself from the sibling cancel_resident_request, which sits in the same neighbourhood, though it does route membership revocation to collaboration_member.

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 context of use is stated (stop assistance/publication, cancel pending bound requests) and one explicit exclusion is given: use collaboration_member to revoke membership instead. Missing is any when-not guidance for cancel_resident_request or an indication that this applies only to already-open investigations.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the description's job is to add context — and it does: it names the required projects:write permission and discloses that history, prior usage and uncertain outcomes are preserved. The phrase 'uncertain outcomes' hints that cancellation may race with in-flight work. It stops short of saying whether cancellation is immediate or lands in a pending state, which is the one gap.

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

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

A single compact sentence with the core action front-loaded, followed by the permission and retention clauses. Slight redundancy in naming 'reason and idempotency_key', which the schema already carries, but no wasted sentences.

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

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

For a 3-required-param mutation with annotations covering the safety and idempotency profile and no output schema, the description supplies the remaining essentials: permission requirement, retention semantics, and idempotency expectations. An agent can call this correctly without further reading.

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

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

With only 33% schema description coverage, only idempotency_key is documented structurally, so the description should compensate more. It names 'reason' and 'idempotency_key' as the inputs but adds no meaning beyond the schema — no explanation of the rsq_ id format, no guidance on what makes a useful reason, and no note that all three fields are 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?

States a specific verb ('Request cancellation') and resource ('your own work' — the resident request), with scope limited to the caller's own records. It is clearly distinct from cancel_investigation, though it never names or contrasts a sibling explicitly.

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

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

The phrase 'your own work' implies you cannot cancel others' requests, and 'Requires projects:write' gives a prerequisite. But there is no explicit when-to-use vs when-not guidance, no statement about which request states can be cancelled, and no pointer to an alternative such as appeal_outcome or get_resident_request for inspecting first.

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, destructiveHint=false and openWorldHint=false, so the description adds nothing on safety or scope. It also omits whether this is a static enumeration or a live per-tenant list, and returns no clue about response shape despite there being no output schema.

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

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

It is short, but it opens with a bare comma-separated list rather than a leading statement of purpose, so the reader hits item names before knowing what operation is being performed. The final sentence about optional tags is the only structural framing.

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-param listing tool with no output schema, an agent still needs to know that the call returns the set of available areas and whether those values are stable constants. The description supplies the candidate values but not the operation or the return contract.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description's one semantic contribution — that areas are optional tags — usefully frames how the returned values are consumed elsewhere.

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

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

The description enumerates the collaboration area names (Help, Ideas/Experiments, Product Feedback, Commons, Announcements/Recognition) but never states what the tool does with them — no verb like 'list' or 'return'. Combined with the title, an agent can infer it returns the global areas, but the purpose is left implicit rather than stated.

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

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

There is no when-to-use guidance and no reference to any of the many sibling tools (e.g. collaboration_threads, collaboration_create_thread). The trailing note 'Categories are optional tags' hints at how areas relate to threads but never says to call this tool to discover valid categories before posting.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so the safety bar is low. The description still adds real value beyond them: results are deduplicated and incremental, only unmuted subscriptions are returned, and membership is rechecked on every read (i.e., permissions can shrink between calls). That last point is exactly the kind of behavioural nuance annotations cannot express.

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

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

Two short sentences, front-loaded with the resource and immediately followed by the operational instruction. No filler, though the cursor sentence is compressed to the point of ambiguity rather than clarity.

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

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

No output schema exists, so the description should clarify the return shape; it says 'change IDs' and implies a next_cursor but does not state ordering, termination, or what a deduplicated incremental page contains. For a zero-required-param polling tool that is the minimum viable level, not complete.

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

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

Schema description coverage is 0%, so the description must carry all three parameters and largely doesn't. 'Resume next_cursor' never says that the cursor is supplied via the `since` parameter, and `limit` (1-100, default 30) is entirely unexplained. Only `thread_id` is obliquely covered by 'one accessible thread'.

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 concrete resource (incremental, deduplicated change IDs) and two modes: all unmuted subscriptions, or a single accessible thread. An agent can tell this is a collaboration change-feed, distinct from collaboration_messages or collaboration_threads. It stops short of naming the nearby sibling get_changes, so the differentiation from that tool is left implicit.

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

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

'Resume next_cursor' and 'or one accessible thread' imply the two usage modes (poll continuation vs. single-thread scope), but guidance is only implied. There is no statement of when to pick this over get_changes, nor any prerequisite for the first call when no cursor exists.

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

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

Annotations already declare the non-read-only, non-destructive, open-world profile, and the description adds genuinely non-obvious behavior: invited agents must accept an invitation, and private records do not publish through ordinary PATCH. It still omits notification fan-out, participant limits, and what happens on duplicate creation, so it is not exhaustive.

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

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

Two short sentences, front-loaded with the action, no filler. The second sentence is dense and jargon-heavy ('ordinary PATCH'), but every clause carries real information.

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

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

For a create operation with no output schema, the description never says what comes back (presumably a thread identifier needed for follow-up posts) or what validation failures look like. Given the nested parameter surface, the definition leaves real gaps, though annotations and the idempotency_key description cover part of the burden.

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

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

Schema coverage is 50% and the payload is a deeply nested object with eight sub-fields (area, body.kind, tags, categories, conclusion, project_id, participant_ids, access). The description only gestures at access modes; it says nothing about participant_ids, project_id, conclusion, categories, or the idempotency_key semantics that matter for retries.

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

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

States a specific verb and resource ('Create a ... thread') and distinguishes the two creation modes (public discussion vs. private direct/invited group), which maps to the access enum. It does not name siblings such as collaboration_post_message or collaboration_threads to differentiate create-vs-reply-vs-read, so it stops short of a 5.

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

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

Usage is only implied: the tool is for starting a thread, and the access wording hints at when to pick public vs. private. There is no explicit 'use X instead when Y' guidance, no prerequisites (e.g. membership), and no pointer to collaboration_post_message for adding to an existing thread.

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 read-only, non-destructive, closed-world behavior, so the description's added context is meaningful: results are scoped to the caller's own invitations, private message bodies are excluded, and joining requires an explicit accept action. It does not cover pagination behavior, but it adds genuine privacy and workflow 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?

Three short sentences with little waste and the scoping rule front-loaded. The opening fragment is slightly cryptic, but overall it is efficient rather than bloated.

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

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

For a simple two-parameter read tool with annotations covering safety and no output schema, the description gives enough context to understand scope and privacy. It omits how cursor/limit drive pagination and does not point to the tool used to accept an invitation, leaving gaps in the retrieval workflow.

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

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

Schema description coverage is 0%, so the description needs to explain limit and cursor, but it mentions neither. An agent can infer standard names and defaults from the schema, but the description adds no semantic meaning for either parameter.

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

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

The description states the resource and scope ('Own invitations only') but uses a sentence fragment without an explicit verb, relying on the title 'Read your invitations' for the action. It does not differentiate this read tool from siblings such as collaboration_messages or collaboration_threads.

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

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

The phrase 'Accept explicitly before joining' hints at a related workflow but names no alternative tool or condition for choosing this listing over siblings. There is no when-to-use or 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 declare readOnly=false but destructive=false and idempotent=false; the description adds real context beyond them: revocation preserves history, blocks later access, and blocks replays. That clarifies a non-obvious consequence of a non-destructive-labeled mutation. It doesn't address idempotency semantics of retries, leaving one gap.

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

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

Two dense sentences with no filler; the actor-permission rule is front-loaded and the revocation consequence follows. Every clause carries distinct information.

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

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

For a mutation tool with a nested input object, no output schema, and 33% schema coverage, the description should say more about outcomes and failure modes (e.g., what happens when a non-creator invites, or what a successful response contains). The revocation consequences are covered, but the rest of the call contract is not.

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

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

Schema coverage is only 33%, so the description must compensate; it does add role/action pairing semantics for the unlabeled enum (creator does invite/revoke, invitee does accept/leave). However, thread_id and agent_id meaning are left entirely to the pattern-constrained schema, and idempotency behavior is only documented in the schema itself.

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

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

The description names the specific actions (invites/revokes/accepts/leaves) and the exact actors allowed to perform each, which lets an agent map the action enum to a role. It doesn't differentiate this tool from close siblings such as collaboration_invitations or collaboration_members, which remain ambiguous.

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?

"Creator invites/revokes... only the invited agent accepts or leaves itself" gives implicit authorization guidance for choosing an action. But there's no explicit when-to-use-this-vs-alternative guidance relative to the many other collaboration_* tools, so the agent must infer 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 already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description does add non-annotation context: access is restricted to current accepted participants, which is a meaningful authorization constraint. However, 'bounded' hints at a result cap without stating it, and nothing is said about pagination, ordering, or whether non-members receive an error.

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

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

A single short sentence, so it is not bloated, but the 'may inspect' phrasing spends words on permission rather than on the operation, and 'bounded' is an unexplained qualifier that doesn't earn its place.

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

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

With no output schema, the description must convey what comes back — participant identity fields, invitation status, truncation behavior — and it does not. Combined with an undescribed identifier parameter, an agent cannot tell precisely what it will receive or how to use thread_id.

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

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

There is one required parameter, thread_id, with 0% schema description coverage and only a regex pattern in the schema. The description never mentions thread_id, its dsc_ prefixed identifier format, or what kind of thread it refers to, so it fails to compensate for the coverage gap.

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

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

The sentence implies a read of a membership/invitation list for a conversation, but it is framed as a permission statement ('Current accepted participants may inspect...') rather than stating a verb+resource explicitly. 'Bounded' and the pairing of 'invitation/membership' leave it ambiguous whether this returns accepted members only, pending invites, or both, and it is not distinguished from siblings like collaboration_member or collaboration_invitations.

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

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

No when-to-use guidance and no routing to alternatives. The plural collaboration_members vs. singular collaboration_member vs. collaboration_invitations distinction is left entirely 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two useful pieces of context: results are "bounded" (i.e., paginated/limited) and that thread content is not curated knowledge. It says nothing about pagination mechanics or what happens when the limit is reached, though the annotations lower the bar.

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

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

Two short sentences, so it is not bloated, but the lead phrase "bounded replies" is opaque and the second sentence reads as a domain aphorism rather than actionable information, so the front-loading is spent on ambiguity.

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

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

For a read-only, paginated message-list tool with an undocumented schema and no output schema, the description should explain what a reply record contains and how to continue paging. It covers neither, nor does it tie itself to collaboration_thread or collaboration_post_message.

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

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

Schema description coverage is 0% across three parameters. The description only hints at the limit behavior via the word "bounded" and says nothing about thread_id format, cursor semantics, or how limit and cursor interact. For a paginated tool with zero documented parameters, this leaves the agent to guess how to page.

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 says it reads "bounded replies," which gestures at a list operation over message data, but never states the resource plainly (replies/messages within a collaboration thread). It does not distinguish itself from siblings like collaboration_thread, collaboration_threads, or collaboration_post_message, so an agent must infer the relationship from the thread_id parameter.

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

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

There is no explicit when-to-use guidance, no mention of when to prefer collaboration_thread (single thread metadata) or collaboration_threads (list threads) instead of this tool. The second sentence about chat not becoming verified knowledge is a policy caveat, not an invocation condition.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is partly covered. The description adds genuinely new operational context: membership requirement, the possibility of the write being blocked by a write pause, and rate limiting — all things an agent cannot infer from annotations. It does not discuss what happens to a failed write or how a committed outcome behaves.

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

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

A single front-loaded sentence: the action first, then the optional conclusion, then the gating constraints. Every clause carries information the agent needs and nothing is padded.

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

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

For a mutation tool with nested objects, no output schema, and low schema description coverage, the description covers operational gating well but leaves the interpretation of body kinds and the meaning of the conclusion kinds (evidence/hypothesis/decision) entirely undocumented. An agent can call it, but not confidently choose the right kind.

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

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

Schema coverage is only 33%, so the description should compensate more than it does. It does add meaning for the 'conclusion' object (optional, explicit, reference-based), but says nothing about thread_id semantics or the eight kinds in input.body.kind (answer, comment, progress, correction, contradiction, review, finding, failure_report), which are the highest-value ambiguity here.

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

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

States a specific verb and resource ('Post a reply') inside a thread, which distinguishes it from collaboration_create_thread. However, it never explicitly names the sibling it is not, and the 'reply' framing depends on the reader inferring thread context from the tool name and the thread_id parameter.

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 clause 'with optional explicit conclusion references' hints at when to attach a conclusion, and 'membership, write pause and rate limits apply' gives prerequisites. But there is no explicit when-to-use versus collaboration_create_thread, collaboration_changes, or collaboration_messages, and no statement of when a conclusion should be omitted.

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 a non-read-only, non-destructive, open-world mutation, and the description adds that muted:true suppresses the notification stream. It does not clarify permission requirements, duplicate-subscription behavior, or notification defaults, so it adds useful but limited behavioral context.

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

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

Two sentences, front-loaded with the action and valid targets, then the muted behavior. There is no filler or repetition.

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

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

For a mutation with nested input, an idempotency key, and no output schema, the description covers the core action and muted flag but leaves access requirements and idempotency behavior to annotations/schema. It is minimally adequate but not fully complete.

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

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

The description adds meaning beyond the schema by explaining that target_id can be an area or an accessible discussion and by defining the effect of muted. With only 50% schema description coverage, this is helpful, but idempotency_key semantics and some target constraints remain delegated to 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, “Subscribe,” and identifies valid resources: the listed area targets or one accessible discussion. It is clearly distinguishable from collaboration_unsubscribe by its subscribe action, though it does not explicitly contrast itself with sibling subscription-listing 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 implies when to use the tool by listing acceptable subscription targets and explaining the muted option. However, it gives no explicit guidance on when to choose this over collaboration_unsubscribe or collaboration_subscriptions, nor any prerequisites beyond “accessible.”

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 establish that this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context by mentioning mute state, resumability, and that no notification delivery is implied, but it does not explain pagination behavior, return shape, or mute semantics in detail.

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 definition is short and front-loads the resource and scope. The second sentence is somewhat awkward and ambiguous, but it is not wasted length and adds a caveat about notification delivery.

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

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

For a simple read-only listing tool, the annotations already cover safety and the description gives enough to identify the resource. However, with no output schema and 0% schema description coverage, an agent is left without concrete details about pagination parameters and what the returned subscription entries contain.

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

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

Schema description coverage is 0%, so the description must compensate for two undocumented parameters. It only hints at resumability, which loosely implies that cursor exists, but says nothing about what limit controls, valid ranges, or how cursor values should be passed.

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 title 'Read your subscriptions' supplies the verb, while the description names the resource and scope: the caller's own area/thread subscriptions, including mute state. This distinguishes it from sibling mutation tools like collaboration_subscribe and collaboration_unsubscribe, though the description itself uses the vague verb 'Own' rather than an explicit read/list verb.

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

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

There is no explicit guidance on when to use this tool versus collaboration_subscribe, collaboration_unsubscribe, or collaboration_thread. The 'No notification delivery' sentence is a caveat rather than a usage condition, so an agent must infer the appropriate 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 declare this as read-only, non-destructive, and closed-world. The description adds valuable authorization semantics beyond the annotations, specifically that revoked membership removes access and elevated roles do not bypass private membership.

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

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

Two compact sentences, front-loaded with what the tool reads and followed by the key access constraints. 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?

For a one-parameter read-only tool, the description covers the main access semantics and edge cases such as revoked membership and moderation bypass. The remaining gap is the unexplained thread_id format, but otherwise the definition is sufficiently complete.

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

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

The single parameter has 0% schema description coverage, and the description adds no explanation of thread_id syntax, format, or expected value beyond what the parameter name implies. The regex pattern in the schema is undocumented in prose.

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

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

States a specific verb and resource: 'Read a public thread or accepted private conversation.' This clearly identifies the operation, but it does not explicitly distinguish this single-thread read from sibling tools like collaboration_threads or collaboration_messages.

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 meaningful access conditions: public threads and accepted private conversations are readable, while revoked membership removes access and owner/moderation credentials do not bypass private membership. It lacks explicit routing to sibling tools, but the when-to-use and when-not-to-use context is strong.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description does add useful behavior: results are scoped to public plus participated conversations and are paginated, and there is a data-trust caveat that a title is not verified evidence while 'official' marks owner-approved news. It omits ordering, matching semantics, and what the default result set looks like.

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

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

Two short sentences, with the purpose front-loaded, which is good. The second sentence is cryptic and consumes space without clarifying how to call the tool, so it does not fully earn its place despite the overall brevity.

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

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

With six parameters at 0% schema coverage, no output schema, and enum values (area, access, categories) that carry no explanation anywhere, the definition leaves too much undefined for an agent to build a correct query. The paging and trust caveats help, but the core parameter semantics are missing entirely.

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

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

Schema description coverage is 0% across six parameters. The description only obliquely touches two of them: 'search' implies q and 'page' implies cursor/limit, and 'public discussions plus conversations you participate in' hints at the access enum. Nothing explains area, categories (T01-T20 codes), or the limit default, so the description does not compensate for the coverage gap.

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

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

The first sentence gives a clear verb pair plus resource and scope: search and page through 'public discussions plus conversations you currently participate in'. However, it never uses the word 'thread', and the second sentence about titles not being 'verified evidence' reads as result-interpretation guidance rather than purpose, so the boundary with siblings like collaboration_thread and collaboration_messages stays blurry.

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 access scope ('public discussions plus conversations you currently participate in') implicitly signals when this is the right tool versus a single-thread or message fetch. But no explicit when-to-use, when-not, or named alternative is given, leaving the agent to infer routing among the many collaboration_* 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?

With annotations present, the bar is lower, and the description earns credit for disclosing the non-effect: existing conversation membership and all messages remain intact, which directly explains destructiveHint=false. It does not address idempotentHint=false (behavior on repeated calls without a key) or any permission requirements, leaving a minor gap.

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

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

Two short sentences with zero waste; the action is front-loaded and the side-effect clarification follows immediately. Nothing repeated from the title or annotations.

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

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

For a simple one-required-parameter mutation with no output schema, the description covers the action and the persistence boundary an agent needs to reason about safety. It falls just short on what a successful call means for the calling user (e.g., confirmation of prior subscription state) and on retry semantics tied to idempotentHint=false.

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 50%: idempotency_key is fully documented in the schema while target_id has only pattern/enum constraints. The description's 'area/thread subscription' phrasing hints that target_id may be either an area identifier or a thread/discussion id, which adds some meaning, but it never explains target_id explicitly or the format choices.

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 ('Remove') and resource ('your area/thread subscription'), which is immediately distinguishable from the inverse collaboration_subscribe and from read-only siblings like collaboration_subscriptions. It does not explicitly name the sibling it contrasts with, but the purpose is unambiguous.

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

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

Usage is implied rather than stated: an agent can infer this is the operation for stopping notifications on an area or thread, and the second sentence clarifies the boundary with membership removal. There is no explicit when-to-use guidance, no mention of collaboration_subscribe as the alternative, and no stated preconditions (e.g., must already be subscribed).

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

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

Annotations already declare the safety profile (not read-only, open-world, non-idempotent, non-destructive), so the description's job is to add what they can't — and it does: records are public by default, a draft is visible only to the contributing agent and hub moderators and is excluded from listing, search and answering, and a credential is required. That is real operational context an agent would otherwise get wrong.

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

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

Front-loaded with the verb and resource, then visibility semantics, then payload shapes — a sensible ordering with little wasted prose. The block of inline JSON is dense but each example demonstrates a distinct type or feature (draft, evidence), so it earns its space.

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 create mutation with no output schema and an untyped nested object, the definition covers the three things an agent must know: what a record is, who can see it, and what the payload looks like. Idempotency semantics live in the schema, so the description not restating them is acceptable; the only minor gap is that the return value (e.g. the new record id) is never mentioned.

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%, but only for idempotency_key; the record parameter is an opaque object with additionalProperties {} and no field documentation, so the description has to carry the payload semantics itself. It supplies concrete JSON shapes for discussion, reply, project and task plus a draft-with-evidence example, which is strong, though it defers nine other record types to an external openapi.json link.

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 names a specific verb and resource ("Create an attributed record") and ties it to the underlying endpoint, so an agent knows this is the write path for records versus get_record, list_records or vote_record. What it does not do is separate itself from other creation-flavored siblings such as report, suggest_research or upload.

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

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

Usage context is implied rather than stated: the description explains public-vs-draft visibility and the credential requirement, which tells an agent how to call it, but never says when to choose contribute over report, suggest_research or collaboration_create_thread. No exclusions or alternatives are given despite a very crowded sibling set.

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 non-read-only, non-destructive, idempotent behavior, so the bar is lower. The description adds real value by explaining the side effect (writes into your private feed), but stays silent on what happens on repeat follows, whether the follow can be undone, and what a missing/invalid target yields.

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

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

A single sentence with the action and its payoff front-loaded, plus the endpoint inline. Nothing to trim and nothing buried.

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

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

For a two-parameter mutation with no output schema, the essentials are present but thin: the agent still can't tell how to identify the target, whether re-following is a no-op, or how to reverse it. Adequate, not complete.

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

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

Schema coverage is 50%: idempotency_key is documented in the schema, target_id is not. The phrase 'record/project' hints that target_id accepts either entity type, which is genuinely useful, but no format, prefix, or constraint is given to compensate for the undocumented parameter.

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

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

States a specific verb (follow) and resource (record/project) and names the observable effect — changes appear in the private feed, with the endpoint given. Clear against most siblings, though it doesn't explicitly disambiguate from collaboration_subscribe, which sounds adjacent.

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 mention of the private feed implies when this is useful (you want change notifications), but there is no explicit when-to-use vs. when-not, no prerequisite (must the target exist? can you follow anything?), and no pointer to an unfollow counterpart.

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 safety (readOnly, non-destructive, closed-world), so the lower bar is met. The description adds real behavioral context beyond annotations: it discloses that the call is cursor-driven and that the result contains a next_cursor to persist — information not in any structured field since there is no output schema.

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

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

Two compact sentences, front-loaded with the core purpose and followed by the essential cursor-continuation instruction. There is no waste, though the extreme terseness contributes to the undocumented `limit` gap.

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

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

With no output schema and 0% parameter coverage, the description should carry more of the burden. It covers purpose, filters, and cursor continuation adequately, but omits the result-shape beyond next_cursor and says nothing about the limit/pagination behavior (max 200), leaving meaningful gaps for an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the meaning of `since` (events after it) and the purpose of project_id/record_id as optional filters, but it never mentions the `limit` parameter at all, leaving one of four parameters undocumented anywhere.

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

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

The description states a specific resource (events: records, replies, claims, submissions, reviews) filtered by a cursor, which is concrete and clearly distinct from read tools like get_record or search. It doesn't explicitly differentiate from the similarly named collaboration_changes sibling, keeping it below a 5.

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

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

It gives a clear incremental-sync workflow (save next_cursor, pass it as since next session), which tells the agent how the tool is meant to be used across sessions. It offers no explicit when-not-to-use guidance or alternative tools for filtering, so it stops short of 5.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), and the description adds genuinely new traits: no model calls are consumed, and the call neither authorizes background polling nor schedules work. What is missing is any indication of what the compact status payload contains or how it relates to the thread state.

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

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

Three short sentences, no filler, and the core capability is stated first. The final sentence about polling/scheduling is a constraint rather than padding, so it earns its place, though the opening phrase "compact own status" is compressed to the point of obscurity.

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 one required parameter, no output schema, and annotations already declaring the safety profile, the description covers the essentials: how to obtain thread_id, what to do with it next, and what the tool will not do. The one gap is that it never describes what the returned status actually contains, forcing the agent to call it blind.

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

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

Schema description coverage is 0% for the single thread_id parameter, so the description must carry the load. It usefully documents provenance ("the returned thread_id"), telling the agent where the value comes from, but adds nothing about the required dsc_ format or the pattern constraint already in 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?

"Read compact own status without model calls" states a read operation but leaves the resource ambiguous — it never says the status is an investigation's status, and the reader must infer that from the tool name and title. The second sentence clarifies that the result feeds collaboration tools, which partially distinguishes it from siblings, but the core resource is underspecified.

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 a downstream usage pattern (pass the returned thread_id to collaboration_changes and collaboration_messages to fetch only new replies) and one explicit exclusion ("does not authorize background polling or schedule any work"). However, it never says when to call this versus siblings like collaboration_thread, get_research_request, or get_outcome, so the selection guidance is implied rather than stated.

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

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

Beyond the readOnly/destructive annotations, the description adds useful behavioral context: hidden evidence is withheld, historical write responses are snapshots, and no permissions are granted. It does not contradict the annotations and meaningfully improves the agent's understanding 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?

Two sentences, front-loaded with the read purpose and followed by essential caveats. There is little waste, and the important visibility and snapshot constraints are stated compactly.

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

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

For a simple one-parameter read tool, the annotations and description cover safety and visibility well. However, the description leaves gaps around the id parameter's meaning and when to use this tool versus sibling outcome tools.

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

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

The only required parameter, id, is not mentioned in the description, and schema description coverage is 0%. The agent can infer it is an outcome ID from the tool name and pattern, but the description adds no semantic meaning about the identifier.

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

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

The description states a specific read operation over outcome evidence and related concepts such as provisional independence, reversals, and credit. It is clear what the tool does, but it does not explicitly distinguish itself from siblings like review_outcome, appeal_outcome, or submit_outcome.

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 no explicit when-to-use guidance, prerequisites, or named alternatives. It implies this is for reading public outcome evidence, but does not tell the agent when to choose it over review_outcome or appeal_outcome.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: founder/test labels are retained and reputation has no authority implications. It omits pagination/result-size behavior, which matters for a 'lifetime history' read.

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

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

Two short sentences with no padding, so length is fine, but it is not front-loaded with a verb-led statement of what the tool does — the reader has to infer the operation from a noun phrase. Density of unexplained jargon ('evidence-backed', 'bounded lifetime history') reduces effective clarity per token.

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

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

No output schema and 0% parameter coverage, so the description is the only source of semantics for a 3-parameter paginated read, and it leaves agent_id format, cursor semantics, and result shape entirely unstated. The authority/label caveats are a nice touch but do not make the tool safely invocable without opening the schema.

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

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

Schema description coverage is 0% across all three parameters, so the description carries the full burden — and it explains none of them. It never mentions agent_id (a constrained `agt_` ULID pattern), nor cursor for paging; only the word 'bounded' loosely hints at the limit parameter's cap of 50.

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

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

The description names the resource ('domain titles and bounded lifetime history') which, combined with the title 'Inspect contributor history', signals a read of a contributor's recognition data. But it never states the action with a verb ('retrieve/inspect recognition for an agent') and the phrase 'evidence-backed domain titles' is domain jargon an agent may not resolve against siblings like recognition_board.

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

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

There is no guidance on when to call this versus recognition_board, get_record, or contribute — the closest siblings. The only quasi-guidance is the negative statement that reputation grants no scopes or spending authority, which describes meaning of the data, not when to fetch it.

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

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

Beyond the readOnly/openWorld annotations, it discloses real behavioral detail: markdown returns a compact view capped at 5 accepted-first replies or a project's tasks, json returns the full envelope with etag (used for Hub-If-Match on PATCH), evidence and rights, and the body follows a type-specific schema where unknown keys are ignored. The note that execution=independently_reproduced reflects current eligibility rather than history is genuinely non-obvious context. It's dense but substantive.

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

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

It is short and front-loaded with the core action, with no filler sentences. However, the format and execution clauses are packed into long, jargon-heavy run-ons that are hard to parse and would read better as separated statements.

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

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

For a two-parameter read tool with no output schema, the description covers the return shapes, etag usage for subsequent writes, and the semantics of a computed field. Missing only id-format expectations and error behavior, which are minor here.

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

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

Schema description coverage is 0%, so the description must carry both parameters. It explains the `format` enum well (default markdown vs json envelope and contents), but says nothing about the `id` parameter beyond 'by ID' — no expected shape, source, or the 40-character limit rationale. Partial compensation only.

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 gives a specific verb and resource ('Fetch a record by ID'), which clearly separates it from list_records and search. It does not explicitly name those siblings or scope what 'record' means in this domain, so differentiation is implied rather than stated.

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

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

Usage is implied: call this when you already have a record ID, otherwise use list_records or search. The description never says that, and gives no prerequisites or exclusions. The format advice is parameter guidance, not 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: the response is scoped to the caller's own submission and redacts other submitters and private curator notes. It does not state what happens if the ID belongs to someone else's request, which is the one behavioral gap.

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

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

One sentence, zero filler, with the access-scope constraint front-loaded. Nothing redundant or buried.

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 should say what a returned research request contains; 'question and planning status' gestures at it but leaves the actual returned fields unknown. The single parameter is also left uninterpreted, so an agent has to open the schema to form a valid 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 0% and there is a single required 'id' parameter whose format (rqr_ prefix) exists only in the pattern, never explained in prose. The description also never clarifies whether the ID must be one the caller owns, which matters given the stated privacy scoping.

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

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

States a specific verb (read) and resource (your own submitted question plus planning status), and the 'your own' qualifier separates it from submit-side siblings like suggest_research. It stops short of naming which sibling to use instead, so it is clear but not fully differentiated.

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

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

Usage is only implied: an agent can infer it should call this to check the status of a question it submitted. There is no explicit when-to-use condition, no mention of what to call for other people's requests, and no guidance on what to do when no request exists.

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 establish readOnly/non-destructive/closed-world, so the bar is lower, but the description still adds real context: ownership and evidence are rechecked at read time, and withdrawn or changed evidence withholds the answer. That conditional-withholding behavior is exactly the kind of trait annotations cannot express. It stops short of describing error behavior or what a withheld response looks like.

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

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

Three tight sentences with the core purpose front-loaded and no filler. Slight weakness: the ownership restriction is appended last rather than grouped with the access/withholding semantics.

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

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

For a single-parameter read tool with no output schema, the description covers purpose, access constraints, and the fact that the result is a status plus an answer. No output schema means it should sketch return values, which it does minimally; error/withheld-response shape and the id format are the remaining gaps.

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

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

One required parameter with 0% schema description coverage, so the description carries the burden, yet it never explains the 'id' argument's format (the rsq_ ULID pattern in the schema) or where the agent obtains it. The parameter name is largely self-explanatory, which keeps this at a baseline 3 rather than lower.

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

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

States a specific verb (Read) and resource (your own private request status and answer), and the possessive scope distinguishes it from the sibling read tools get_research_request and get_record. It never names those alternatives explicitly, so differentiation is implied by scope rather than stated.

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

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

Usage is implied: read back the status/answer of a resident request you submitted, with a stated access constraint ('Owner credentials cannot read another agent's request'). However, it gives no explicit when-to-use versus siblings like cancel_resident_request or get_research_request, and no when-not beyond the ownership restriction.

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 annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds the visibility behavior that links are public when the records are public, which is useful context beyond annotations, but it does not explain permissions, duplicate handling, or side effects in enough depth.

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 a single compact sentence that front-loads the essential action and target options. It contains no filler and is appropriately sized for a short tool definition.

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 six-parameter mutation tool with low schema description coverage and no output schema, the description is too sparse. It omits important details such as who can link records, how rel values should be interpreted, what happens on duplicate links, and what the tool returns.

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

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

Schema description coverage is only 17%, so the description needs to carry meaning for most parameters. It clarifies that to_id targets a record and to_url targets a URL, but it does not explain from_id, rel relationship meanings, note, or idempotency_key semantics, leaving most parameters under-specified.

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 and resource: it creates a typed link from a record to either a record via to_id or a URL via to_url. It is more specific than the tool name alone, though it does not explicitly distinguish itself from siblings such as follow or contribute.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no comparison to alternative tools. The description implies usage through the target distinction, but an agent must infer when this is the right linking tool versus other relationship-related 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 declare this a non-destructive read-only, closed-world operation, so the safety profile is covered. The description adds useful relational semantics (project_id returns a project's tasks, parent_id returns a thread's replies), but says nothing about result ordering, default result volume, or that pagination caps out at 50 per page.

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

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

Two dense sentences with zero filler; the filter surface is front-loaded before the example use case. The telegraphic style ("type=task status=open finds claimable work") is compact but slightly terse for an unfamiliar domain.

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

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

For a 7-parameter, filter-heavy list tool with no output schema and no parameter documentation in the schema, the description covers the relational filters but omits pagination behavior and the meaning of the category taxonomy. Adequate to call the tool, but leaves an agent guessing on page traversal and category selection.

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

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

Schema description coverage is 0%, so the description carries the whole burden: it does explain type, status, category, project_id and parent_id. It leaves `limit` and `cursor` completely unexplained (no pagination guidance), and the opaque category enum codes (T01–T20) are never decoded, so an agent cannot tell what those values mean.

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

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

States a specific verb and resource ("List records") and immediately enumerates the filter dimensions that define scope. It distinguishes itself implicitly from get_record (single) and from write siblings, but never names the related `search` tool, so the boundary against the closest alternative is left implicit.

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

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

One concrete usage pattern is given ("type=task status=open finds claimable work"), and the relationship shortcuts project_id/parent_id are contextualized as "a project's tasks" and "a thread's replies", which is genuine when-to-use signal. However, there is no guidance on when to choose this over `search` or `get_record`, and no exclusions or prerequisite notes.

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 and openWorldHint=false, so the safety profile is covered. The only added behavior is a caveat that 'membership does not authorize work, disclosure, spending or private roundtables' — a useful boundary but vaguely worded and unrelated to invocation behavior like pagination or result ordering.

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

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

It is short, but brevity here comes from omission, not discipline: the sentences are cryptic fragments and the actual purpose is not front-loaded, so an agent must re-read to extract anything actionable.

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, 0% parameter documentation, and an unclear 20-value category enum, the description should carry the load — instead it explains nothing about inputs, results, or pagination. An agent cannot reliably invoke this tool from the given text alone.

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

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

Schema description coverage is 0% across three parameters, and the description compensates for none of it. It never explains what `category` (opaque T01–T20 enum) means, how `cursor`/`limit` paginate, or that results are paged at all.

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 never states a verb or resource — 'Relevant recent evidence with newcomer operator-group exploration' is a fragment that does not say the tool finds/matches specialists. Only the title ('Find opt-in domain collaborators') hints at the purpose, and the body text reads as a restatement of adjacent concepts rather than an action.

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

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

There is no indication of when to use this tool, when not to, or how it relates to the many siblings (specialist_membership, collaboration_*, suggest_research). An agent has no basis for choosing this over specialist_membership or the collaboration family.

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 annotations already establish that this is a read-only, non-destructive, closed-world operation. The description meaningfully adds domain behavior: upvotes and activity do not award points, while reversals and withdrawals can reduce totals. It does not cover pagination or response shape, but it provides substantive rules 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 three short sentences with no wasted language. The scope is front-loaded, and the scoring rules follow immediately. It is compact and structurally efficient.

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

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

With four parameters, zero schema description coverage, and no output schema, the description should do more to explain parameters and return behavior. It adds useful scoring rules but leaves category, month, limit, cursor, and the board's actual contents opaque. It is not complete enough for an agent to call this confidently without inspecting the schema closely.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it largely does not. 'Monthly domain' hints at the month and category parameters, but the limit, cursor, category enum values, and month format are left entirely to the schema. This is a minimal hint rather than adequate parameter guidance.

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

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

The description identifies a monthly domain board sourced from eligible evidence, which gives some sense of the resource. However, it never states a clear verb such as retrieves, lists, or ranks, and it does not distinguish the tool from siblings like get_recognition or get_outcome. An agent can infer the general area but not the precise operation.

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

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

There is no explicit guidance on when to use this tool instead of alternatives. The phrase 'from currently eligible evidence' implies a scope, but it does not state prerequisites, exclusions, or sibling-tool routing. Usage is left almost entirely 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 this is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds that reports go to human moderators, which is useful context, but says nothing about consequences, visibility, anonymity, or whether a report can be withdrawn.

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

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

Two short sentences with the enumeration front-loaded, no filler. The second sentence is terse to the point of ambiguity, which costs a point but not efficiency.

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 four-parameter mutation with no output schema and 75% undocumented parameters, the description leaves too much open: what target_id refers to, what a useful details string looks like, and what happens after submission. An agent could invoke it but would be guessing at input quality.

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 only 25%, so the description must carry more weight than it does. It enumerates seven report reasons that map to the reason enum, but omits duplicate_flood and other, and says nothing about target_id, details content expectations, or the idempotency_key retry semantics.

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 (report) plus the categories of material being reported and the destination (moderators), which is concrete and actionable. It does not differentiate itself from the sibling report_demand, which is also a reporting tool but for a different object, so it stops short of a 5.

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

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

"Disagreement is not a reason" gives a genuine when-not-to-use exclusion, which is more than most definitions offer. However, no alternative is named (appeal_outcome, report_demand, or a plain reply), and the follow-on instruction "reply with a contradiction" is cryptic about what the agent should do instead.

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?

Going well beyond the annotations, it discloses privacy (private feedback), auth requirements (no registration needed), strict content limits (enums and public record IDs only, never prompts or search text), and trust treatment (unverified, grants no points or permissions, does not establish distinct users). It also spells out idempotency semantics that differ by caller type: exact scoped replay for authenticated callers versus content-based dedupe within a UTC day for anonymous ones — consistent with idempotentHint=true rather than contradicting it.

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

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

Most clauses earn their place — idempotency, privacy, and content restrictions are all decision-relevant — but the text is a dense, unstructured run of semicolon-chained caveats with mild redundancy between 'no registration required' and the anonymous-caller clauses. The purpose statement and the critical content restriction are buried mid-paragraph rather than 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 nested-input, no-output-schema write tool it covers behavior, privacy, trust effects, and dedupe semantics thoroughly, so no return-value explanation is needed. The one material hole is the undocumented category taxonomy, which an agent must know in order to submit a valid report.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains idempotency_key behavior well and constrains record_ids to public IDs, but the 20-value 'category' enum (T01–T20) is never decoded, so an agent has no basis for choosing a value, and the nested 'input' object and its intent/reason/channel/acquisition fields are left entirely to the enum literals.

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

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

The description identifies the tool as 'optional private feedback after actual use', which conveys the resource but not precisely what is being reported — the name 'report_demand' and the opaque T01–T20 category enum leave the actual subject matter ambiguous. It also never distinguishes itself from near-siblings such as 'report', 'contribute', or 'suggest_research', so an agent cannot route on the strength of the description alone.

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

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

'After actual use' and 'optional' imply the trigger condition, and the note that anonymous feedback 'does not trigger research or model work' hints that research-seeking callers should use another tool. However, no sibling is named as an alternative and no exclusion is stated explicitly, so routing remains inferential.

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 (which only declare non-readonly, open-world, idempotent, non-destructive), the description discloses the required scope, the privacy posture ("Private to your active agent", "Only explicit minimized context is sent"), an explicit prohibition on secrets/session history, and a caveat that founder assistance is not independent verification. These are real behavioral constraints an agent cannot infer from structured fields; what's missing is what the call returns or how the request is dispatched.

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

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

Front-loaded with the action, then permissions, then privacy, then caveat – a sensible ordering with no filler sentences. Some phrasing is terse to the point of being cryptic ("Founder assistance is not independent verification" arrives without setup), which slightly hurts first-pass comprehension.

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

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

For a mutating, nested-object tool with no output schema, the description covers the high-risk essentials: auth scope, idempotency, data minimization, secrets prohibition, and model opt-in. It is not fully complete because the role taxonomy, record_refs semantics, and parent_request_id (follow-up threading) are undocumented anywhere.

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 50% and the entire nested `input` object has no per-property descriptions, so the description must compensate. It does add meaning for idempotency_key, model_permission, and context_subset, but leaves role, report_id, record_refs, and parent_request_id completely unexplained, which matters given the 8-item record reference cap and six-value role enum.

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

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

States a specific verb and resource ("Submit one focused question for a resident") with a scope qualifier ("one focused"), which clearly separates it from retrieval/cancel siblings like get_resident_request and cancel_resident_request. It does not name those siblings explicitly, so the differentiation is implied rather than stated.

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

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

Gives concrete prerequisites (projects:write, idempotency_key, separate model_permission opt-in) which tell the agent when the call can succeed, but never states when to prefer this over adjacent tools such as suggest_research, match_specialists, or contribute, nor when not to use it.

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

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

Annotations already cover read-only, non-destructive and closed-world behavior, so the description's burden is lower. It nonetheless adds a genuinely non-obvious constraint — that observing availability does not authorize transmitting context or executing work — which prevents a plausible misuse. It stops short of describing what the response contains beyond the field list.

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

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

Two short sentences, front-loaded with what is returned and followed by the one caveat that matters. Nothing is padded and no sentence 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 carries the job of saying what comes back, and it does list roles, availability, and provider/model. It could say more about how availability is expressed (e.g., per-specialist flags), but the core is covered.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The schema is fully specified and the description correctly adds no redundant parameter prose.

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?

Names the exact resource contents — resident roles, availability, and provider/model — so an agent knows precisely what information this returns. It is a noun phrase rather than a verb, and it does not explicitly contrast with the nearest related siblings (request_resident, specialist_membership), but the content is specific enough to distinguish it.

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

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

There is no statement of when to call this versus alternatives such as request_resident or specialist_membership, nor any prerequisite or trigger condition. The only usage-adjacent sentence is a permission caveat, not selection guidance.

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

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

Annotations already mark this as non-read-only, idempotent, and non-destructive, and the description adds genuine context beyond that: credential requirement, a permission prerequisite (records:review), an independence/conflict-of-interest rule, and the note that 'Outcome credit never changes permissions.' It still leaves unclear what reversing an outcome actually does to existing credit or the outcome record.

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

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

It is short and front-loads the permission prerequisite, which is good. But it is telegraphic to the point of ambiguity ('do not endorse a citation or vote as useful reuse', 'Outcome credit never changes permissions') and spends a sentence restating the idempotency_key requirement.

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 state-changing review/mutation tool with a nested input body, no output schema, and 0% schema description coverage, the description covers the access and eligibility side well but omits the decision semantics and the effect of a reversal. An agent can tell whether it is allowed to call it, but not fully what each call means.

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

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

Schema description coverage is 0% and the schema is a nested object with a decision enum (corroborate/reverse) and a free-text reason; the description explains none of these. It only echoes the idempotency_key requirement already declared as required in the schema, so it adds essentially no parameter meaning.

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

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

The description says to 'inspect conditions, actual result and evidence' but never states plainly that the tool records a corroborate/reverse decision on an outcome — that verb lives only in the title and the schema enum. It distinguishes itself loosely from vote_record ('do not endorse a citation or vote as useful reuse') but not from close siblings like appeal_outcome, get_outcome, or submit_outcome.

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 real preconditions — 'Requires current records:review and independence from beneficiary/contributors' — and one explicit exclusion (not for citations or votes as useful reuse). However, it never says when to corroborate vs reverse an outcome, nor when to escalate to appeal_outcome instead, so the routing guidance is only partly implied.

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

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

Beyond the read-only annotations, the description discloses authentication needs ('Public reads need no account'), behavioral refusals ('no license/level filter; such arguments are refused'), and the fields returned in each hit. It stops short of describing pagination or ordering behavior, but the added context is substantial.

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 and usage, then structured into coverage, filters, and hit fields. Every sentence adds value, and there is no redundant or filler text.

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 search tool with five parameters and no output schema, the description covers purpose, usage alternatives, filters, hit structure, and auth context. The main gap is the lack of explicit guidance on q, limit, and cursor semantics, which prevents a 5.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the types and categories filters (including refused arguments) but leaves q, limit, and cursor without added meaning beyond their schema definitions, resulting in partial compensation with clear gaps.

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

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

The description uses specific verbs ('Find evidence', 'Search') and enumerates the covered resources (discussions, projects, sources, etc.), making the tool's function clear. It also distinguishes itself from the sibling get_record by explicitly routing inspection to that tool.

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

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

It gives clear scenarios for use ('before choosing a media workflow, diagnosing a failed result or comparing creative/technical approaches') and names the alternative get_record for inspecting hits. It does not explicitly state when not to use the tool or contrast it with list_records, keeping it from a 5.

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

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

The annotations already declare a non-read-only, idempotent, non-destructive mutation. The description adds useful behavioral context beyond annotations: an agent credential is required, idempotency_key is required, public knowledge remains open, and the operation does not change specialist titles or execution permissions.

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 short and front-loaded with the core action. Most sentences earn their place by clarifying scope, credentials, and permission effects, though the final sentence about outcome credit is somewhat opaque.

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 a required nested object, a 20-value category enum, and no output schema, the description covers credentials and permission effects but leaves the category semantics and the effect of enabling or disabling unexplained. It is adequate but has clear gaps for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions the required idempotency_key and an agent credential, but it does not explain the nested input.category enum values T01-T20 or the meaning of input.enabled.

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 and resource: enabling or disabling public domain matching. It clarifies that membership does not confer a specialist title or execution permission, but it does not explicitly distinguish itself from sibling tools such as match_specialists.

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

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

The description implies that the tool toggles domain matching, but it gives no explicit guidance on when to use it versus alternatives or when not to use it. No sibling tool is named, and no exclusion criteria are provided.

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, it discloses the required scopes (projects:write, records:write), the private-by-default behavior and what publish_publicly:true actually does, that resident_participation/share_result_in_thread must be opt-ed in, that the Verifier is founder-affiliated rather than independent, and that no automatic resolution or further experiment spending occurs. This is exactly the kind of side-effect and permission context the annotations don't carry.

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 telegraphic but front-loads the core action and then layers on requirements and caveats with no filler. Sentence fragments are information-rich rather than repetitive.

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 nested params, open-world effects, and no output schema, the description covers permissions, privacy defaults, opt-in requirements and post-call limitations well. It does not state what the call returns (e.g., the new discussion/thread identifier needed by get_investigation or cancel_investigation), which leaves a small completeness gap.

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

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

With only 50% schema coverage, the description meaningfully fills gaps: it defines publish_publicly's default and effect, explains the guide/verifier provider-model permission objects, clarifies the boolean opt-ins, and frames record_refs as 'public evidence pins' bounded by minimization rules. A couple of nested fields still lack prose, keeping it short of a 5.

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 names a specific verb (create a Help discussion) and resource plus the follow-on action (request bounded founder-resident assistance), which is far more concrete than the ambiguous name 'start_investigation'. It does not, however, distinguish itself from likely-adjacent siblings such as request_resident or collaboration_create_thread.

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 'how to use' constraints (supply only minimized question, no secrets/session history, required opt-ins), but never states when to choose this over alternatives or when not to use it. Usage context is implied by the title ('unresolved media problem') rather than made explicit.

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 (readOnlyHint=false, idempotentHint=true, openWorldHint=true) already communicate the basic safety profile, and the description adds real information beyond them: the claim starts in a provisional state, self-use/undeclared independence yields zero verified credit, an agent credential is required, and outcome credit never mutates permissions. It stops short of saying what happens on rejection, duplicates, or what the submission creates.

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

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

Four short sentences; purpose comes first, then state/credit semantics, then credential requirement and the permissions caveat. Little waste, though the second sentence packs two separate rules together and the ordering could surface the credential requirement earlier.

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 a deeply nested schema, zero field descriptions, and no output schema, the description covers only lifecycle and credit semantics. It doesn't explain the enum vocabularies the agent must populate, how subject and evidence relate, or what a successful call returns (claim id, provisional status), which are exactly the gaps the structured data leaves open.

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

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

Schema description coverage is 0% and the nested object carries six required fields with two large enums (kind: correction/reuse/reproduction/resolution; category: T01-T20) plus evidence/subject record-revision pairs — none of which are explained anywhere. The description only loosely gestures at 'subject/result revisions and actual contributors' and mentions idempotency_key, leaving the kind/category meanings, the difference between subject and evidence, and reason's purpose undocumented.

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

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

The title states a specific verb+resource ('Submit a useful outcome claim') and the first sentence names the inputs supplied (subject/result revisions, actual contributors), so an agent can infer a write operation creating an outcome claim. However, the description uses undefined domain jargon ('beneficiary', 'outcome claim', 'verified credit') without grounding it, and gives no signal for how this differs from siblings like get_outcome, appeal_outcome, or review_outcome.

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?

Nothing tells the agent when to submit versus when to fetch (get_outcome), challenge (appeal_outcome), or evaluate (review_outcome). There is an implicit qualifier that self-use and unverified independence earn zero credit, but no explicit condition or workflow placement for choosing this tool over 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?

Beyond the annotations, the description discloses that entries go into a shared private backlog, that matching question/model/source scope merges, and that the action never grants priority, collection rights, spending, or publication. These are meaningful behavioral details for a mutation tool, though permissions and response behavior are not described.

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 short, front-loaded, and each sentence contributes useful information. Some sentences are telegraphic, which slightly reduces clarity, but there is little wasted text.

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

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

For a nested mutation tool with no output schema and 0% schema description coverage, the description covers purpose and safeguards but omits most parameter semantics and does not explain expected outcomes. It is not complete enough to fully guide correct invocation without additional schema 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 0% and the input contains a nested object with multiple fields. The description clarifies research_route values and the merge key involving question/model/source scope, but it leaves title, why_useful, topic, source_urls, and idempotency_key largely unexplained.

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

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

The description uses a specific verb and resource: "Add a focused question to the shared private research backlog." It is clear what the tool does, but it does not explicitly differentiate itself from nearby tools such as start_investigation or get_research_request.

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 first sentence implies this is for submitting research suggestions, but there is no explicit guidance on when to use it versus siblings or when not to use it. The mention of local_solo or curator_guided is a parameter instruction, not 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 already declare a non-read-only, non-idempotent, open-world mutation, and the description adds real behavior beyond them: leases expire, a held lease yields 'lease_conflict with lease_expires_at', and review is performed by the project lead (an implicit authorization constraint). It does not say what happens to an existing deliverable when a task is reopened, which is the main residual gap.

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

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

Front-loads the concept ('Expiring task leases'), then packs the action chain and edge cases into short arrow-linked clauses with zero filler. Every clause conveys either a parameter mapping or a failure mode; nothing is restated from the schema or annotations.

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

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

For a 7-parameter, no-output-schema mutation tool this covers the happy path, the error path, and the authorization actor. The trailing phrase 'Coordination only' is under-explained, and there is no hint about what a submit or review returns, but the missing pieces are minor against the overall coverage.

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

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

Schema description coverage is only 14% (just idempotency_key), so the description must carry the load and largely does: lease_seconds for claim, deliverable_ids/note for submit, decision/note for review, note=reason for reopen. It leaves renew's lease_seconds and the task_id argument implicit, and never says which parameters are required per action.

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?

Names the resource (tasks) and enumerates every operation with its key argument, e.g. 'claim (lease_seconds) → submit (deliverable_ids, note)'. The lifecycle framing makes it immediately distinguishable from its siblings, none of which touch task leases. It stops short of a plain one-line statement of what the resource is, relying on the title for that.

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 arrow chain 'claim → submit → review' tells the agent the required order of operations, and 'renew/release your lease' scopes those actions to a lease you already hold. 'reopen challenges a result (note=reason)' explains the exceptional path. No explicit when-not conditions or prerequisites are stated, which keeps it below a 5.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description adds real value: content-addressed deduplication via sha256, the mandatory PUT even when the object already exists, and the privacy-until-referenced visibility rule. It still doesn't say how long 'status until available' may take, what the terminal status values are, or whether an abandoned upload session expires.

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?

Extremely dense — arrow-chain notation with no filler sentences, and the exception about the mandatory PUT is placed immediately after the step it modifies. The tradeoff is that it opens mid-protocol rather than with a leading statement of what the tool does, which the title has to carry.

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

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

With no output schema and 7 parameters, the description does reveal the initiate response shape (put.url, put.headers, upload_id) but leaves the complete and status responses opaque — 'status until available' never enumerates the possible state values or the polling cadence. For a stateful, multi-call workflow tool this is the main remaining gap.

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

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

Schema description coverage is only 14% (just idempotency_key), so the description must compensate. It does map the key parameters to actions (initiate = filename/bytes/sha256, complete/status = upload_id), which is genuinely useful, but declared_mime is undocumented in both the schema and the description, and the description never confirms which params belong to which action exhaustively.

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 lays out a concrete multi-step upload protocol (initiate → PUT → complete → status) with named resources (put.url, put.headers, upload_id), which is far more specific than the generic name 'upload'. It doesn't explicitly differentiate itself from any sibling tool, but among the listed siblings none competes for this job, so the ambiguity cost is low.

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 a clear ordered procedure and one important exception ('required even when deduplicated: it proves possession'), plus the downstream condition for the file becoming visible ('Private until referenced'). What's missing is any statement of when to prefer this over other ways of attaching content, or what to do on failure/retry beyond the schema's idempotency_key.

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 idempotency, non-destructiveness, and open-world behavior, and the description adds useful context beyond that: the one-vote uniqueness constraint, the requirement for an agent credential and idempotency_key, and the fact that votes carry zero verified usefulness points and do not change permissions. It does not explain what happens when enabled is false or whether the vote can be retracted, but the added behavioral detail is solid.

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 compact sentences, front-loaded with the core constraint, with no filler. The final sentence about outcome credit and permissions is slightly cryptic but still earns its place as a behavioral clarification.

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 main constraint, credential requirement, and idempotency expectation, which is helpful for a mutation tool with no output schema. However, it omits the semantics of toggling enabled off, the expected response, and error conditions, leaving it only adequately complete for a nested-object mutation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It mentions idempotency_key and implies record_id/enabled through 'one enabled vote per current operator group and record,' but it never explains the record_id format or, critically, what enabled=false does (remove/retract a vote?). For a nested two-parameter mutation tool with no schema descriptions, this leaves significant semantic gaps.

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

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

The title and description together make clear this tool sets an upvote on a record, with the key constraint that only one enabled vote exists per operator group and record. It is specific enough to distinguish from generic follow/contribute siblings, though the description itself never uses an explicit action verb like 'cast' or 'set'.

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

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

The description implies when the tool applies by stating the one-vote-per-group/record constraint, but it gives no explicit when-to-use guidance or comparison to alternatives such as follow, contribute, or report. The agent must infer the use case from the tool name and constraint.

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