Immersive Commons

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

Adds substantial context beyond the annotations: no-auth requirement, the MCP handshake limitation, the public donor wall exposure of donor {name, message}, and error behavior (error_kind:"validation"). It doesn't address rate limits or the irreversibility of an on-chain transfer, so not quite full coverage.

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 purpose and is well organized into purpose, flow, and Args. However, the trailing Args block largely restates the tier description already in the schema, adding some redundancy for a fairly dense paragraph.

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

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

With no output schema, the description correctly enumerates the return values (tiers, payTo, asset + network, donate URL). For a non-trivial multi-step payment flow, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: case-insensitive matching, the side effect of adding selected_tier with the exact atomic amount to sign, and the validation error listing valid labels on an unknown label.

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 (donate) and resource (USDC to Immersive Commons) plus the mechanism (x402 / HTTP 402 + USDC on Base), which is immediately distinguishable from the read-only sibling ic_donations_total. An agent knows exactly what this tool accomplishes.

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

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

Gives clear when/how context: no auth required, the two-step 402 flow, and the manual POST workaround since MCP can't run the in-band handshake. It stops short of naming a sibling alternative (e.g., ic_donations_total for reading totals), so no explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds genuinely new behavioral context: no authentication is required, and because there is no output schema it usefully describes the returned record fields. It stops short of noting ordering guarantees or whether totals are cached/live.

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 return payload and scoped tightly to three sentences. The trailing 'Args: { limit?: ... }' sentence largely duplicates the schema, so it doesn't fully earn its place, but the whole block is compact with no filler.

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

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

For a single-parameter read tool with no output schema, the description covers everything an agent needs: what is returned, that no auth is required, and the limit semantics. Nothing material is missing.

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

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

Schema description coverage is 100% and the single limit parameter's range and default are already fully documented in the schema. The description restates '1-50, default 10' without adding syntax, ordering meaning, or behavior beyond what the schema provides, so the baseline 3 applies.

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

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

Specific verb and resource: it returns the running USD total, donor count, and most recent settled donations shown on the public donor wall. The return payload is enumerated (name, amount, message, tx, ts), so an agent knows exactly what it gets and can distinguish it from the write-side sibling ic_donate.

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 'shown on the public donor wall at /donate' and 'No auth required' imply the read-only public scenario, but the description never states when to prefer this over ic_donate or any other sibling, nor any exclusions. Usage is inferable but not spelled out.

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

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

Annotations already state readOnlyHint=true. The description adds much more: no auth required, identical not_found responses for unknown vs restricted forms, live accepting_submissions state, and the distinction between can_submit and approval_requires_tier. These are important behavioral disclosures not captured by annotations.

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

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

The description is long but front-loaded with the primary purpose and then uniquely critical notices. It uses formatting like bold and intra-description labels to structure the overloaded usage pitfalls. It is longer than necessary in places, but each section contributes to proper agent behavior.

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 provided, the description supplies the return shape and semantics, including the form contents, can_submit, accepting_submissions, and optional reason fields. It also covers error behavior, runtime state caveat, and usage instructions, making the tool self-contained 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?

The schema already provides a description for form_id ('From ic_forms_list. Do not invent one.'), so schema coverage is 100%. The description's mention of 'Form: { form_id }' adds no meaningful semantic beyond the schema, so the baseline of 3 stands.

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 state a clear, specific action: reading the full definition of one form, including questions, question types, requiredness, choice options, and per-question 'why' purpose. It is explicitly contrastive with the sibling ic_forms_submit as the read-before-write counterpart, making its purpose distinct.

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

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

The description explicitly says 'call it before ic_forms_submit' and gives concrete instructions: relay each 'why' to the human, read 'facts' before committing, report both audience and approval_requires_tier, and avoid relying on can_submit alone. This goes beyond implicit context and gives direct 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?

Even with readOnlyHint: true in annotations, the description significantly enriches transparency: it discloses auth behavior (no auth needed, token doesn't narrow), visibility filtering (listed vs omitted forms), and explicitly states listings never contain answers. It explains the rationale for hiding omission, which goes well beyond the annotation contract.

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 longer than average but front-loads the core purpose. Each sentence adds information: the purpose, the START HERE directive, the visibility exclusions, the no-answer guarantee, and the return shape. The only slightly verbose part is the 'program nobody outside can discover' rationale, which is still relevant enough to keep.

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 tool with no parameters and no output schema, the description fully specifies expected return fields (ok, count, forms, and each form's fields) and behavior nuance (what is omitted, what can_submit means). An agent can successfully invoke this tool with no outside knowledge and interpret the result correctly.

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

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

The schema has zero parameters and 100% coverage, so the baseline is 4. The description adds the 'Args: none' line, which is redundant but helpful confirmation. No parameter semantics are lacking.

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

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

The description states a specific verb ('list'), resource ('every form Immersive Commons is currently taking answers to'), and the key scope: filtered by who you are. It also differentiates from siblings by explicitly saying 'START HERE — do not guess a form id,' which signals that this is the entry point for form-related tools and disambiguates from ic_forms_get/submit.

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

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

The description provides clear when-to-use context: 'START HERE — do not guess a form id' tells an agent to call this before any form-specific tool. It also explains when a token matters and when it doesn't. However, it doesn't explicitly name sibling tools or provide exclusions (e.g., 'for a single form use ic_forms_get'), so it falls short of a perfect 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?

With readOnlyHint already set true, the description adds valuable behavioral context beyond annotations: no token required, no auth required, the two access paths, the id-alone failure mode, the consistent found:false result for any invalid input, and the explicit non-return of stored answers or reviewer notes. No contradiction with annotations.

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

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

The description is front-loaded with the most important fact: 'your own, never anybody else's', and the structural Arg/Return framing at the end helps parseability. It is verbose by strict standards, with a couple of repeated ideas ('No token required' and 'No auth required'; id-alone warnings appear twice), though the repetition is used to reinforce a critical security rule.

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

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

Given there is no output schema, the description adequately explains the return shape and semantics: { ok, found, submission? }, what submission contains (status, dates, failed gates), and what it never contains. The security model and both invocation modes are fully spelled out for a security-sensitive tool.

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

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

The schema has 100% description coverage, so baseline value is already met. The description adds meaningful semantic context beyond the schema: the relationship between claim_token and submission_id, the 'id alone never works' constraint, and the security rationale. This elevates it above a bare schema readout.

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: it reads the status of one submission and 'never anybody else's'. It clearly distinguishes itself from general form/submission tools by emphasizing the own-submission-only behavior and the identity/token mechanisms.

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

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

The description gives explicit when-to-use conditions: signed-in identity resolves the record with no id, or submission_id plus claim_token opens the record. It also gives when-not guidance: an id alone never works, wrong tokens all return found:false, and the tool cannot be used to test which ids exist.

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 provide only four thin booleans (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the full burden — and it exceeds it: no token required for public forms, live audience-ring checks, one-submission-per-identity semantics, claim_token returned once and only for unattributed submitters, and the explicit warning that this writes a real submission under a real person's name and every answer must be confirmed with the human.

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?

For a high-consequence tool, nearly every sentence earns its place — preceding tokens, audience checks, this-activity semantics, idempotency, claim_token duties, and return shape are all load-bearing. The structure is an information-dense single paragraph, though, and the critical warning to confirm every answer sits mid-stream; paragraph breaks and strict warning-front-loading would tighten it.

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 only two parameters, the description must carry return-format and failure-mode disclosures — and it does: it enumerates the exact return (ok, submission_id, status, failed_gates, claim_token?, counts, message), explains the claim_token governance, the audience-ring refusal behavior and its difference from 'no such form', and the semantics of the submission. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100% and the schema already documents both parameters thoroughly, including that answers are keyed by question id exactly as ic_forms_get returns them and that booleans admit multiple string forms. The description's 'Args: { form_id, answers }' restates schema information and names ic_forms_get as the source of the keys, but adds little new meaning, so the baseline of 3 applies.

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

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

States a specific verb + resource ('Submit answers to one form'), scoped to a single form, and the ensuing text distinguishes it from its read-side siblings ic_forms_get and ic_forms_list. The purpose is unambiguous without needing to open the schema.

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

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

Explicitly instructs the caller to run ic_forms_get first to obtain question ids and allowed options, and explains when NOT to use the tool — a correction must go to the form's contact address because a resubmit is refused and the first submission is never overwritten. It also frames the real-world semantics of the action (expression of interest, not a final application), telling the agent what to tell the human.

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

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

The description directly contradicts the annotations: it explicitly claims idempotency ('Idempotent: a record that was already withdrawn comes back ok with changed: false', 'a retry after a timeout is safe'), while the annotations set idempotentHint to false. Per the scoring rule, a contradiction with annotations forces a score of 1. Otherwise the description is rich with behavioral detail, but this contradiction is disqualifying.

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

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

The description is long and somewhat repetitive, restating consequences already in the title and over-explaining ownership. However, given the consequential and irreversible nature of the operation, the detail is largely justified and front-loaded with the core purpose. Every major point contributes to safe usage, though tighter editing would improve it.

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

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

Even though there is no output schema, the description explains the important return fields ('found', 'changed', 'freed_slot', 'counts', 'message'), covers idempotent retry behavior, addresses ambiguous error semantics for nonexistent ids, and details edge cases like already-withdrawn records and approved submissions. This is complete enough for an agent to invoke the tool safely and interpret the response.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema: it explains the two valid identity paths (signed-in identity versus submission_id plus one-time claim_token), clarifies that a signed-in submitter needs neither token, and reinforces that submission_id and claim_token must be used together. This helps an agent choose the correct parameter combination for the caller's situation.

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

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

The description clearly states a specific verb and resource: it withdraws the human's own submission to a form. It also sharply distinguishes itself from siblings by emphasizing that only the submitter can perform this action, and that operators, reviewers, and admin permissions cannot. This makes the tool's purpose unambiguous even among many form-related siblings.

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

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

The description explicitly says when to use the tool, when not to use it, and who is allowed to call it. It states that operators/reviewers/admins cannot withdraw on someone's behalf, that withdrawal is not a way to redo an application, that the agent must confirm with the human before calling, and explains the implications for approved submissions. This is strong, actionable usage guidance.

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

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

With readOnlyHint=true and openWorldHint=false already present, the description adds substantial context: no auth is required, this is a rules table not a progress report, items with no `requires` are granted to every signed-in member, and condition shapes ({ signal, gte }, { minTier }, { minLevel }) are explained. This goes well 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 front-loaded with purpose and usage, and the condition semantics are valuable. It is slightly repetitive (twice states 'No auth required') and includes an Args block that largely duplicates the schema, but the Returns block compensates since no output schema exists.

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

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

Given no output schema, the description explains the return shape ({ ok, count, items[{ id, kind, label, blurb?, rarity, requires?, asset? }] }) and the meaning of condition structures. It also clarifies auth requirements and the distinction from progress tracking, leaving no critical 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 100%, so the single `kind` parameter is already fully documented with its enum. The description restates the same enum values and confirms it is optional, adding no semantic detail beyond the schema; baseline 3 is appropriate.

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

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

The description states a specific resource (the full catalog of Funko Me unlocks) and what it includes (conditions that earn each one). It explicitly distinguishes itself from sibling tools ic_funko_progress and ic_funko_levels, so an agent can tell what it does without opening the schema.

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

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

It gives explicit when-to-use guidance ('explain to a human WHY something is locked, or to show what is worth doing on the floor') and names the alternative for per-member progress (ic_funko_progress). The reference to ic_funko_levels for level rules further routes the agent correctly.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description adds substantial behavior: 'Levels never go down', which records earn XP versus which do not (check-in vs RSVP, verified vs claimed quest, published log vs draft, the membership ring earns nothing), the 50/week GitHub cap, and that each source carries a `how` field for advising a human. This is real context beyond the structured data.

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

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

Purpose is front-loaded and the enumerations are informative rather than filler, but the 'No auth required' statement is repeated verbatim at the start and end, and the XP-source list is long enough to be a mild drag. Slightly tighter editing would help.

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

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

With no output schema and no parameters, the description carries the burden well: it names the return shape ({ ok, version, xp_sources[...], levels[...], rules[] }) and explains what each piece contains. An agent has everything needed to call and interpret it.

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

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

There are zero parameters, so the baseline is 4. The description confirms 'Args: {}' and even sketches the return payload, which is more than the empty schema provides, but there is no parameter meaning to add.

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

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

The description opens with a specific resource and scope: the level rules table — every XP source with rate/cap plus the 10-level curve. It explicitly contrasts itself with ic_funko_progress ('nobody's progress'), so an agent can distinguish it from the sibling that reports one member's level.

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

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

It states when to use this tool (you want the rules/curve) and names the alternative for the other case ('for one member's level call ic_funko_progress'). No auth requirement is also called out, removing a common source of hesitation.

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 readOnly/openWorld; the description adds substantial disclosure beyond them: signature is null until signed cards ship, members are private by default, unknown/retired/private handles all return the same not_found, reach is filtered to currently-working channels, and payments require explicit human confirmation. That is exactly the kind of context annotations cannot 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?

Purpose and schema name are front-loaded, and most clauses earn their place (payment warning, not_found privacy semantics, capability structure). However it is a single dense run-on paragraph packing nested field-by-field documentation, which is hard to scan and could be broken into structured sections.

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

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

With no output schema, the description fully compensates by enumerating the returned card shape (links, reach, capabilities, pay, offerings, signature), the enum values for channel and auth, and the meaning of available/why/alternative. An agent has everything needed to interpret the response.

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

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

Schema coverage is 100% and the single handle parameter is fully documented there, so the schema does the heavy lifting. The description's 'Args: { handle }' restates the schema and adds only the URL mapping already implied by the handle description. Baseline 3 for a fully-covered single 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 first clause states a specific verb and resource ('The public card for one Immersive Commons member by handle') and immediately names the response schema ic-member-card/1. It is clearly distinguishable from siblings like ic_offerings_get, ic_forms_get, or ic_donate, which serve different resources.

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 operating context: no auth required, 'follow `how`', and per-capability fallbacks ('when false, `why` and an `alternative` to use instead'). It also rules out one misuse ('this is not a membership oracle') and states a precondition for payment (show your human first). It stops short of routing the agent explicitly between sibling tools.

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, and the description goes well beyond them: it discloses privacy defaults, the collapsed not_found response, retired-handle redirection, draft suppression, and 'Read-only. No auth required.' That is exactly the behavioral context an agent needs before calling.

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

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

Purpose is front-loaded in the first clause, but the return-shape enumeration is a long, dense run-on that is hard to parse. It earns its place because there is no output schema, but the packing into one block reduces readability.

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

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

With no output schema, the description carries the full return-value burden and does so thoroughly, enumerating profile_v2, stats, log, activity, and follow blocks plus error semantics. Combined with annotations covering safety, nothing an agent needs to call correctly is missing.

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

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

Schema coverage is 100% and the single 'handle' parameter is fully documented in the schema with the same /m/<handle> example the description uses. The 'Args: { handle }' line adds nothing beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource+scope: one Immersive Commons member's public profile by handle, delivered 'as data'. The '(public)' framing and the profile-vs-card distinction let an agent separate it from the sibling ic_member_card_get without opening either schema.

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

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

Gives strong contextual guidance: the same profile_v2 block as the agent.json URL, drafts never surface, members are private by default, and unknown/private/hidden/retired handles all collapse to the same not_found so it is explicitly 'not a membership oracle'. It never routes to a named alternative such as ic_member_card_get, so it stops short of explicit when-to-use-vs-alternative.

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

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

Annotations already cover read-only and closed-world, so the bar is lower; the description still adds the ranking behavior (highest-velocity-first, ties preserve feed order) and the no-auth fact. It does not mention rate limits or pagination, but for a bounded top-N feed that matters less.

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 what is returned and how it is ranked before the field enumeration and args. The parenthetical field list (dek, beat, date, publishedAt, image, focal) is useful since there is no output schema, though it makes the sentence dense.

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

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

With no output schema, the description compensates by enumerating returned fields, stating sort order, tie-breaking, and auth requirements. An agent has everything needed to call and interpret the result.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema. The inline Args block largely restates ranges, defaults, and even the substring-over-title-and-summary definition, adding little beyond the schema — baseline 3.

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

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

States a specific verb+resource (velocity-ranked AI news) and immediately contrasts itself with the ic_signal_* family, calling out THE SIGNAL weekly dispatch as a different surface. An agent can distinguish this tool from its siblings without opening any schema.

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

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

It names the closest alternative family (ic_signal_*) and characterizes what that serves versus this raw aggregator firehose, which effectively routes the agent. It stops short of an explicit 'use this when / not when' rule, but the context is clear.

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

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

Annotations only cover readOnlyHint and openWorldHint, but the description adds substantial behavior: the uniform not_found semantics, the HTTP 402 / x402 PaymentRequirements flow, payTo being the member's own address on Base and Solana, the PAYMENT-SIGNATURE/X-PAYMENT headers, and the reminder to show the human price and promise before paying. This is well beyond what annotations provide.

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

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

Front-loaded with the core lookup purpose, and the return shape is given compactly. The payment-flow detail is dense and arguably heavy for a read tool, but each sentence serves a real caller need, so only minor trimming is warranted.

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 documents the return object in detail (ok, handle, count, offerings fields, how_to_pay) and covers the downstream payment mechanics. Nothing an agent needs to call it or interpret the result is missing.

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

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

Schema description coverage is 100% and there is only one parameter, whose schema already documents the handle format. The description restates 'Args: { handle }' without adding syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource+scope: 'What one Immersive Commons member sells, by handle', and enumerates the return shape. An agent can immediately tell this is a per-handle offerings lookup, distinct from siblings like ic_member_card_get or ic_donate.

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?

Clarifies exactly which offerings are returned (listed and on sale) and that unknown handle, empty member, and private member all collapse to not_found. It also explains the purchase path (GET/POST x402_url). It does not explicitly name an alternative sibling to use instead, but the context is clear.

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

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

Annotations only say readOnlyHint=false / destructiveHint=false / idempotentHint=false; the description adds genuinely useful behavior beyond that: no auth needed, 'The other person sees only the final proposal', vetoes are 'never attributed', and unknown is 'never counted as ok'. It still doesn't say whether a second call overwrites a prior answer (idempotentHint is false but the consequence is 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?

Front-loaded with audience, then the action, then the privacy constraint ('there is no field for them'), then the args shorthand and auth note. Efficient, though the inline Args blob partially duplicates the schema rather than earning new information.

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

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

For a nested, multi-variant tool with no output schema, the description covers the common verdict/rank path well and delegates the PSI private-times/private-venues branches to the schema's detailed field descriptions. The one gap is return behavior: with no output schema, it says what the counterparty sees but not what this call hands back to the 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 100%, so the schema already documents every parameter (including the psi/psi_venues/common_* private-plan variants). The description's Args blob is a useful shorthand and clarifies rank '1 = best' and that unknown counts as non-ok, but adds no semantics beyond what the schema already states. Baseline 3 applies.

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

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

The description states a specific verb and resource ('Judge each option... send only a verdict and optional rank per option, and ok per time window') and pins the audience ('For the GUEST of a plan or their assistant'), so the operation is unambiguous. It does not, however, name or differentiate itself from the very close sibling ic_plans_guest_respond, which the agent must disambiguate on its own.

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 context: this is the guest-side answering action, and it explicitly notes 'No auth required' (the token authorizes it). It does not state when NOT to use it or name an alternative tool (e.g. ic_plans_guest_respond / ic_plans_guest_get), so the routing guidance stops just short of 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?

Adds substantial context beyond the annotations: the token is the sole credential, a wrong token returns not_found identically to a missing plan (closing an enumeration oracle), and the payload deliberately excludes the other side's answer. That is strong auth and privacy disclosure. It never explains the annotations' readOnlyHint=false / idempotentHint=false, so any side effect of the call is left undocumented.

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 audience and the security model, and the return contents follow immediately; almost every clause earns its place. Minor redundancy: 'NO IC ACCOUNT NEEDED' and 'No auth required' say the same thing, and the Args line duplicates the schema.

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

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

With no output schema, the description correctly carries the return-value burden and does so well (specific fields returned and deliberately withheld), and it covers auth, errors and input shape. The only omission is any mention of side effects, which is notable given readOnlyHint=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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning by framing token as the credential and describing its failure mode, plus identifying plan_id's origin (ic_plans_create / ic_plans_list). The 'Args: { plan_id, token }' line itself is redundant restatement of the schema.

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

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

The description states a clear verb+resource (read a plan as its invited guest, using the link token) and enumerates exactly what comes back: options, windows, your own answer, the current proposal and next_step. It implicitly separates itself from owner-side plan tools by insisting on the guest/token framing, but it never names the neighboring guest tools (ic_plans_guest_answer, ic_plans_guest_respond), so differentiation is inferential rather than explicit.

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

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

It clearly scopes the caller: 'For the GUEST of a plan, or the guest's own AI assistant. NO IC ACCOUNT NEEDED' tells an unauthenticated agent that this is the right entry point, which is real usage context. It does not, however, say when to prefer it over the sibling guest_answer/guest_respond tools or what to do once the plan has been read.

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 mark this as a non-read-only, non-idempotent, non-destructive mutation, and the description adds real context beyond that: it commits the person, both sides accepting confirms the plan, passing reveals nothing about why, and leave:true ends the plan for both. It adds no output/return or retry behavior, but the declared side effects are meaningful.

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

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

Dense and front-loaded, with the audience, the decision, and the commitment warning leading. The repeated inline Args block is somewhat redundant given the 100%-covered schema, but overall the sentences earn their place.

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

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

For a small 4-param mutation with no output schema and full schema coverage, the description supplies the key outcomes (confirmation, next proposal, plan termination) and the 'no auth required' note. It is nearly complete, only missing routing guidance against the sibling tool.

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

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

Schema coverage is 100% and the schema already documents accept, leave, token, and plan_id, so the description's repeated 'Args: {...}' list adds little. The prose does add semantic meaning for accept (true accepts / false passes) and leave (ends it for both), but the schema covers this too.

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

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

States a specific verb+resource ('accept or pass on the current proposal, or leave the plan') and scopes the audience clearly ('For the GUEST of a plan or their assistant'). However, it never differentiates itself from the close sibling ic_plans_guest_answer, leaving an agent unable to tell the two apart from 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?

Gives clear context and consequence-based guidance: accept vs pass moves to the next proposal, leave ends the plan, and 'ASK YOUR PERSON FIRST, it commits them' frames the decision. It does not name when to choose a sibling tool (e.g., ic_plans_guest_answer) over this one.

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 readOnlyHint already declared, the description still adds a lot: no auth required, 40 questions/hour per token plus a shared anonymous budget, the advice to pass a token, and the 'at most 3 hits per talk' cap. It also states retrieval-only behavior and describes the exact return payload, which annotations do not cover.

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

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

Purpose and the retrieval-only constraint are front-loaded, followed by budget then a compact Args/Returns block. It is dense and readable, though the Args restatement duplicates the schema and the Returns enumeration is long for a single line.

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

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

There is no output schema, so enumerating the return fields (slug, talk_title, series, speaker, similarity, slide, snippet, deep_link, detail_link, via) is genuinely necessary and included. Auth and rate-limit behavior, the per-talk hit cap, and the retrieval-only nature are all 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?

Schema description coverage is 100%, so both q and k are fully documented with ranges and default in the schema itself. The description's Args block largely restates those constraints (1-500 chars, 3-25, default 10) rather than adding new semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource: semantic search over all Immersive Commons talks returning matching slides. It also distinguishes itself from the sibling list/get tools by framing itself as the '/presentations search box' equivalent, and it explicitly says it is retrieval only, not a generated answer.

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?

Clear context for use (find slides by meaning, then read snippets and follow deep_link) and it explicitly excludes the generated-answer expectation. It does not name ic_presentations_list or ic_presentations_get as the alternative for enumerating talks, so the agent must infer that routing itself.

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 (safe read). The description adds useful behavioral context: no auth required, returns full record, includes content field as a distillation, error behavior with listing available entries, and ambiguity resolution (newest wins). This goes beyond annotations.

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

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

The description is information-dense but front-loaded with the main purpose. It includes details on return format, error handling, and related tool usage without being overly verbose. Could be slightly tighter but each sentence adds value.

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

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

Despite no output schema, the description fully explains the return object fields, error behavior, and the nature of the content field. It covers all essential aspects for correct invocation and understanding.

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

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

Input schema already has 100% coverage with descriptions for both parameters. The description adds semantic context: session_no is VCN-only, series disambiguates across programs, and explains ambiguity resolution. This enhances understanding beyond the schema.

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

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

The description clearly states the tool fetches a single presentation by session number, with optional series disambiguation. It distinguishes from sibling ic_presentations_list, which is for listing and discovering non-VCN talks. The verb 'fetch' and resource 'single presentation' are specific.

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

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

Explicitly states when to use this tool (VCN-only talks with session_no) and when to use ic_presentations_list (non-VCN talks like ClawCamp). Also mentions no auth required, which is helpful for selection.

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 indicate readOnlyHint=true, and the description confirms 'No auth required.' It goes beyond annotations by detailing the return structure, explaining the scaffold flag meaning placeholder data, and noting that public_url may be null for unpublished items. No contradictions with annotations.

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

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

The description is richly packed but efficiently structured: purpose first, then differentiation, auth, parameters with examples, and expected return format. Every sentence adds unique value without repetition, making it both comprehensive and easy to parse.

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

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

Despite having no output schema, the description fully documents the return shape and edge cases (scaffold, unpublished presentations). Combined with the thorough parameter and usage details, the tool is completely understandable without further references.

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

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

Schema coverage is 100%, and the description adds context beyond the schema: examples for series values ('VCN'|'ClawCamp'|'Talk'), default/max for limit and its application scope, and an explicit note about case-insensitive filtering. This fully compensates for any lack of deeper 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?

The description clearly states 'List the public archive of presentations given at Immersive Commons events...', specifying the verb and resource. It explicitly differentiates from sibling tools ic_resources_list and ic_presentations_get, making the tool's unique purpose unmistakable.

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

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

The description provides explicit guidance: when to use (listing public presentations), when not to (not for rooms, not for detail), and alternatives (ic_resources_list, ic_presentations_get). It also notes that no authentication is required and that results are grouped by series.

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 cover read-only/open-world, but the description adds far more: the incomplete-success contract for ok:true/complete:false, coverage.unknown_minutes and unknown_windows[], the rule that unknown windows are omitted rather than assumed free, horizon.effective_to clamping semantics, and explicit 'NO TOKEN REQUIRED' auth disclosure. This is exactly the extra behavioral context annotations cannot 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?

Front-loaded with the two facts an agent needs first (slots + policy together, then the read-order rule). The return-shape enumeration and the negotiation metaphor add length; the metaphor sentence is stylistic rather than informational, but the rest of the length is earned by genuinely non-obvious 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?

No output schema exists, yet the description enumerates the full response shape (ok, complete, member, meeting_type fields, slots, coverage, unknown_windows, horizon, generated_at), explains the empty/incomplete cases, and discloses auth requirements. An agent could call and interpret this correctly without further probing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description reinforces semantics the schema states and adds cross-parameter meaning: start/end are UTC ISO-8601 with trailing Z, member.tz and viewer_tz are IANA zones and wall-clock arithmetic is forbidden without one, and the arg list is restated. Useful but largely overlapping with the schema.

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

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

States a specific verb+resource (open slots for one meeting type) and an unusual scope addition (the member's full booking policy in the same response). It is clearly distinguishable from ic_scheduling_list_meeting_types, which it references as the source of the meeting_type slug, and from ic_scheduling_manage_booking.

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 strong when-to-use guidance: read the policy block before the slots, understand that complete:false is an incomplete success, and that empty slots with complete:true means genuinely booked. It routes to ic_scheduling_list_meeting_types for the slug, but does not explicitly contrast against ic_scheduling_manage_booking or state when not to call this.

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 cover only readOnly/openWorld, so the description carries the real behavioral load: no token required, visibility filtered in the service's own SQL (members_only/unlisted/deactivated never appear), and what an empty meeting_types means. This is exactly the context an agent needs that 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?

Front-loaded with the core 'what you may book' statement followed by usage, semantics, and the return shape. It is dense and somewhat long, but nearly every sentence carries distinct operational value; only the protocol URL caveat is marginal.

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, yet the description spells out the full return shape (ok, member, meeting_types fields) and the empty-result semantics. For a read-only listing tool, nothing an agent needs to call and interpret it is missing.

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

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

Schema description coverage is 100% and the single handle param is fully documented with a regex in the schema. The description only restates 'Args: { handle }' and hints at slug correctness, adding no syntax beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('list every PUBLIC meeting type' a member publishes) plus the fields returned (duration, location kind, notice window, booking horizon). Clearly distinguishable from the sibling ic_scheduling_get_availability, which it explicitly positions itself as a prerequisite to.

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

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

Explicit 'START HERE' directive, warns that guessing a slug causes not_found, and tells the agent to read min_notice_minutes and horizon_days before proposing times. It also explains the meaning of an empty result, ruling out a misuse interpretation.

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?

Without needing annotations it discloses credential semantics (token IS the credential; wrong token returns not_found so ids can't be probed), cancel idempotency, reschedule atomicity ('an error means nothing changed'), and it never skips authorization, only moves it into the resource. The one mismatch is that annotations declare idempotentHint=false while the description says action:cancel is idempotent — defensible at tool level since reschedule mutates, but it is a nuance the reader must reconcile.

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?

Almost every sentence carries operational payload, but it is delivered as a dense wall of prose with rhetorical asides ('ghosts', 'burns members' time', 'emails a human to be removed') and the purpose is not front-loaded. The size is larger than the task requires; a structured list of auth model / per-action behavior / errors would read far faster.

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 return-shape duty and does so: it documents booking/superseded/cancel_token fields, the NEW-id-after-reschedule rule, meet_link status transitions, and the full error_kind set (not_found, slot_taken, outside_window, too_soon, rate_limited, validation, transient). Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns a step above by explaining parameter interplay the schema cannot — that start must come from a fresh availability call because responses go stale, that idempotency_key is minted server-side if omitted but should be reused on retry, and that reason is member-visible. It still largely restates the arg list.

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

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

The title and body state a specific verb set (read/cancel/reschedule) on a specific resource (one booking) keyed by cancel_token, and the actions are enumerated explicitly. It is distinguishable from siblings and even names ic_scheduling_get_availability as the source of a reschedule slot. Marks off only because the body opens with rhetorical framing ('The way OUT of a booking...') instead of the operational statement the title already gives.

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

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

Explicit 'when' rules throughout: confirm cancel and reschedule with your human first, reschedule needs a start from a FRESH availability call, poll meet_link no faster than every 2s for at most 90s, reuse idempotency_key on retry. It also states which action is safe/repeatable versus which mutates a real calendar.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds 'No auth required,' which is genuinely useful behavioral context beyond the annotations. It also enumerates the returned structure (beats[], stories[], datespan, classification, published), giving the agent a concrete picture of the payload.

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 dense sentences, front-loaded with the core action and return shape, with no filler. The return-field enumeration is slightly run-on but every element earns its place since there is no output schema.

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

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

With no output schema, the description usefully enumerates the return tree and notes that no auth is needed, which covers the main things an agent needs to call and interpret this tool. It lacks any error behavior (e.g., unknown slug) or ordering context, keeping it short of 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 100% with a single required slug parameter already documented as coming from ic_signal_list_issues. The description only restates the parameter and adds an example value ('issue-05'), which is marginal value over the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one issue by slug') and the schema reference to ic_signal_list_issues implies the lookup workflow. It does not explicitly differentiate itself from sibling ic_signal_get_latest, which also returns a single issue, so an agent must infer the distinction from 'by slug'.

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 or when-not-to-use guidance and never names an alternative such as ic_signal_get_latest or ic_signal_search. The only routing hint is the schema note that the slug comes from ic_signal_list_issues, which is workflow inference rather than stated guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered, but the description adds real context beyond them: 'No auth required' and the guarantee that output matches an element of ic_signal_list_issues.issues[]. It does not describe error/empty states or pagination, but for a read-only summary tool this 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?

Front-loads the core purpose and keeps everything in a compact couple of sentences. The inline 'Args:' block partially duplicates the schema's own description, which is slight redundancy, but 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?

No output schema exists, but the description compensates by defining the return shape by reference (same as an element of ic_signal_list_issues.issues[], or stories[] when inlined). Auth requirement is disclosed. Minor gap: no mention of behavior when no issues exist.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning: include_stories=true inlines stories[] with id/title/dek and is justified as avoiding a follow-up call. This explains the *why* and the exact content beyond the schema's terse 'true inlines the issue's stories'.

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 ('returns the most-recent issue summary') and pins down the exact return shape by equating it to 'one element of ic_signal_list_issues.issues[]'. It also names two siblings (ic_signal_list_issues and ic_signal_get_issue), so an agent can distinguish it without opening a schema.

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

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

Frames itself as a 'convenience tool' for grabbing the latest issue and explicitly notes that include_stories=true saves a follow-up ic_signal_get_issue round trip, which gives clear routing context. It stops short of an explicit when-not statement (e.g., when to prefer ic_signal_list_issues or ic_signal_search 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description still earns credit by adding the no-auth requirement and enumerating the returned story tree (body paragraphs, feature card, image, source citations), which matters because 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?

Front-loads the verb and resource, then adds identification format and return contents in a tight sequence. The trailing 'Args: { slug: string, story_id: string }' is pure redundancy against a 100%-documented schema and is the only sentence that does not 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 usefully describes what is returned, plus auth and parameter sourcing. It stops short of noting failure behavior (e.g. unknown slug or story id), which would be the remaining gap for a single-resource fetch.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that story_id is a kebab-case slug and giving concrete examples ('grok-build', 'shai-hulud-2'), which reduces the chance of passing a numeric id.

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

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

States a specific verb+resource ('Fetch one story') and the exact key pair that identifies it, which cleanly separates it from ic_signal_get_latest and ic_signal_list_issues. It does not explicitly name those siblings, so it falls just short of the top band.

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 schema descriptions point to ic_signal_list_issues and ic_signal_get_issue as the source of the two required keys, so an agent can infer the retrieval chain. However, the description itself never says when to prefer this over get_issue or get_latest, and gives no exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: 'No auth required' and the 'Newest first' ordering guarantee, plus the shape of what comes back. It stops short of describing pagination or error behavior.

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

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

One dense paragraph with the purpose front-loaded and zero filler. The Args/Returns clauses read like a struct dump and partially duplicate the schema, but the Returns clause earns its place because no output schema exists.

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 supplies the full return field list, which is essential for an agent to use the result. Combined with the default limit and auth note, it is nearly complete; only pagination/edge behavior is unaddressed.

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

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

Schema coverage is 100% so the baseline is 3, but the description contributes information the schema lacks: the default value of 10. It restates the max of 50, which is already in the schema, making the addition incremental rather than rich.

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 issue summaries for THE SIGNAL') and scopes it ('Newest first'), which cleanly separates it from single-item siblings like ic_signal_get_issue and ic_signal_get_latest. It does not explicitly name those siblings, so it falls short of a 5.

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

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

There is no when-to-use guidance and no named alternative, even though ic_signal_get_latest, ic_signal_get_issue and ic_signal_search are obvious alternatives. Ordering and auth details describe the tool's behavior rather than when an agent should pick 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: no auth required, case-insensitive matching, ranked ordering, and the shape of each hit (snippet, slug, story_id when matched in a story).

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 purpose, then matching fields, then behavior, then return shape, then args — a logical funnel with no filler. Dense but every clause carries information an agent can act on.

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

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

With no output schema, the description correctly compensates by describing the return payload (ranked hits with snippet, slug, and optional story_id). Combined with auth status, matching scope, and parameter constraints, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented with their bounds. The description's inline 'Args' block merely restates q (2-120 chars) and limit (max 50, default 10) without adding syntax, format, or matching semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb (substring search) and resource (every published SIGNAL issue), and the search semantics inherently distinguish it from enumeration siblings like ic_signal_list_issues and lookup siblings like ic_signal_get_issue. The list of matched fields (issue title/dek, beat label/kicker, story headline/dek/body) pins down the scope precisely.

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: reach for this when you have free text to locate within issues rather than a known slug or ID. However, no sibling is named and there is no when-not guidance (e.g., use ic_signal_list_issues for browsing, ic_signal_get_issue for a known slug), so the agent must infer the routing.

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

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

Annotations only say it's a non-idempotent, non-destructive write; the description goes far beyond by disclosing that it files a real application under a real person's name, commits them to a binding program, requires no auth, that a token only attributes, and that a second submission is rejected. It names the exact fields the agent must not fabricate and explains the claim_token is shown exactly once.

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 paragraph is front-loaded with the action and then layers warnings, prerequisites, constraints, and return shape in a logical order with no filler. It is dense and slightly run-on, but every sentence carries new operational 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?

There is no output schema, but the description still enumerates the return object ({ ok, application_id, claim_token, status, failed_gates, cohort, message }) and covers auth, idempotency behavior and the critical claim_token handling. Nothing an agent needs to invoke this correctly is missing.

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

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

With 100% schema coverage the baseline is 3, but the description adds meaning beyond the schema by flagging that nda_ack, commit_5_weeks and in_person_sf answers are 'promises they have to keep' that must be confirmed, and by specifying that all answers need the human's confirmation. This elevates how to treat the required fields, though it doesn't restate enum values the schema already lists.

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 (submit an application) and resource (the 20-person spatial-computing beta) with scope details (5-week, in-person, NDA-bound). It routes the agent to ic_spatial_beta_program for the catalog and implicitly separates itself from the status/read siblings. An agent can tell what this does without opening the schema.

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

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

Gives explicit prerequisites ('Call ic_spatial_beta_program first for the catalog and the exact allowed values') and a hard behavioral rule ('CONFIRM EVERY ANSWER WITH YOUR HUMAN FIRST and never invent one on their behalf'). It also states the one-application-per-email constraint and that duplicates are refused rather than merged.

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 readOnlyHint/openWorldHint, and the description adds materially more: 'No auth required,' the exact return shape { ok, form, cohort }, and the gate semantics that determine outcomes. This is behavioral context beyond structured fields.

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

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

Front-loaded with purpose and action guidance, and every clause earns its place, though the single dense paragraph packs terms, gates, args, and returns together and could be marginally tighter.

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, yet the description supplies the return shape, the no-auth status, and the gating logic an agent needs before invoking apply. Nothing material is missing for a no-arg read tool.

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

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

Zero parameters, so the baseline is 4; the description confirms 'Args: none,' matching the empty schema. Nothing further to document.

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 resource (the Immersive Commons spatial-computing beta program) and enumerates exactly what it delivers: the terms, every application question, and the reason each is asked. It explicitly distinguishes itself from the write sibling ic_spatial_beta_apply.

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

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

Explicitly instructs 'Call this BEFORE ic_spatial_beta_apply so you answer well instead of guessing,' naming the alternative and the condition that selects this tool. It also gives decision guidance on the gates, noting a 'no' to any is very likely a rejection and that honesty beats applying anyway.

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 readOnlyHint already covering safety, the description adds substantial non-obvious behavior: the token acts as a credential because ids leak via URLs/chat logs, wrong-or-missing tokens are indistinguishable from unknown ids (no enumeration oracle), and no auth is required. This is exactly the kind of context annotations cannot convey.

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

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

Front-loads the purpose, then the credential requirement, then the security rationale, then args and return shape. Dense but every sentence carries information; the opening 'Where one application stands' is slightly indirect but quickly grounded.

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, yet the description enumerates the return fields (ok, found, application?, cohort), states the auth requirement, and documents the security semantics of failure modes. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains why both parameters are jointly required and frames claim_token as a credential rather than a plain identifier. It does not add format/syntax detail beyond the sbc_/sb_ prefixes 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?

States a specific verb and resource ('Where one application stands', checked against the spatial-beta application concept) and clearly differs from the sibling write tools ic_spatial_beta_apply and ic_spatial_beta_program by being a read/status lookup. An agent can identify the tool's role without opening the schema.

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

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

Gives clear conditions for use: BOTH application_id and claim_token from submission are required, and it explains that an id alone yields only public slot counts. It stops short of naming siblings explicitly, so routing relies on inference, but the when-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?

Goes well past the readOnly/openWorld annotations: states no auth is required, that unknown filter values are silently IGNORED and surfaced in `notes` rather than erroring, and gives the return envelope. The `first_try_success_label` warning ("not yet measured", not "0%", null must not be rendered as a number) is exactly the kind of trap-prevention context annotations cannot 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?

Purpose is front-loaded and every sentence carries information; nothing is filler. It is one dense block, though — the return-shape detail and the label caveat would scan faster as separated lines, and 'same schema' is an ambiguous aside.

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 supplies the return envelope ({ ok, total, returned, offset, entries[], facets, notes }), explains what `facets` and `notes` are for, and flags the null-vs-zero pitfall. Nothing an agent needs to call it correctly or interpret results is missing.

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

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

Schema coverage is 100% and each parameter already documents its enum values, defaults and the status/evidence orthogonality, so the description is largely restating structured data. The framework it adds (freshness gate, live facet vocabulary) mirrors what the schema already says, so baseline 3 applies.

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

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

Specific verb+resource ('List and filter the Immersive Commons Vault') plus the distinguishing scope: procedures proven to work, no auth. It explicitly separates itself from ic_vault_match, so an agent can pick between them without opening a schema.

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

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

Names the alternative and the condition that selects it ('use ic_vault_match to ask whether a specific company qualifies; use ic_vault_feedback_submit to report whether a recipe worked'). It also tells the agent to read `facets` to discover filter vocabulary instead of guessing, which is actionable usage guidance.

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

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

Goes well beyond annotations by explaining the three-valued semantics, why `indeterminate` is a real answer, how missing fields become `unknown`, how prose-only gates become `manual_review`, and why non-hits on named partner lists are never failures. It also states that every profile field is optional and describes the return shape.

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

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

The description is dense and front-loads the central three-valued verdict model, which is appropriate for a 25-parameter eligibility tool. It is somewhat long and occasionally repetitive in emphasizing that `indeterminate` is not a soft no, but nearly every sentence adds behavioral context.

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 complex 25-parameter tool with no output schema, the description is complete enough: it explains the verdict model, missing-data behavior, auth expectation, partial-profile behavior, and the returned fields including `matches[]`, `failed[]`, `unknown[]`, `manual_review[]`, and per-tier verdicts.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful cross-parameter meaning: all profile fields are optional, missing fields affect verdicts via `unknown`, and the filter set mirrors ic_vault_list. It reinforces rather than duplicates schema semantics, especially around partial profiles and verdict interpretation.

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: evaluate a company profile against the Vault's eligibility predicates. It immediately distinguishes its role from ic_vault_list by focusing on three-valued eligibility verdicts and by saying it accepts the same filters as the list 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?

Gives clear usage context: no auth required, all profile fields are optional, and partial profiles are normal and return more `indeterminate` rather than errors. It also tells the agent to omit `qualify` to see all three verdicts. It does not explicitly say when to use this versus ic_vault_list beyond filter compatibility, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations only cover read-only and closed-world, so this description carries the weight, and it does: ordering (newest first), the tier filtering rule, the meaning of relevant:true, and the no-auth path. It stops short of describing edge cases such as what an expired or malformed token does.

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 resource and the return contract, and the tier rule is stated before the boilerplate args/returns block. The Args and Returns restatements duplicate structured fields and could be trimmed without loss.

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 usefully sketches the return shape ({ ok, tier, signed_in, total, entries }) and explains the two fields that need explaining, relevant and min_tier. Complete enough for a read-only listing tool.

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

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

Schema coverage is 100%, and the description only restates the same bounds ({ limit?: integer 1-100 }) without adding format or semantics the schema lacks. Baseline 3 applies when the schema already does the work.

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?

A specific verb and resource: it returns the 'What's New at IC' changelog in newest-first order, and it anchors that to a concrete surface ('the same list the /whats-new page shows'). That separates it cleanly from siblings like ic_news_get or ic_signal_get_latest, which cover different content.

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 says exactly what you get with and without a token, including that no auth is required, which is genuine when-to-use guidance. What's missing is an explicit contrast with the nearest sibling (ic_news_get), so the agent has to infer that choice itself.

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

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

The description itself is rich: no-auth, ascending seq order, cursor-based incremental reads, and explicit caps (agents max 200, events max 100) plus a 'degraded' flag — behavior an agent cannot get from the schema. However, this read-only, side-effect-free retrieval is labeled readOnlyHint=false and idempotentHint=false in the annotations, a direct conflict that could make an agent wrongly treat the call as a state-changing operation subject to caution.

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 what the tool returns, then the incremental pattern, then the shape of args and response in compact form; nearly every clause carries new information. Slightly run-on (the long first sentence mixes source, contents, and ordering) but no filler 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?

There is no output schema, yet the description fully specifies the return shape ({ ok, cursor, degraded, agents[], events[] }) including result caps and the pagination contract, so an agent knows how to loop. Combined with the no-auth note and the single optional parameter, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description earns more by explaining the operational pattern behind 'since' — it is a resume cursor from your previous call, not an arbitrary offset — and by restating the default 0 and the seq > since semantics in use context.

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 ('Returns the workshop room's live agent-to-agent traffic') and anchors it to a concrete artifact the user can recognize ('the same feed the /workshop/crosstalk wall shows'). It also enumerates the content (agents with skill/call count/last seen; register/call/complete/fail events), which separates it cleanly from the neighboring ic_workshop_status 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?

Gives clear operative guidance for the incremental case ('Pass since = the cursor from your last call to get only newer events') and states the auth precondition ('No auth required'). It does not name an explicit alternative or exclusion, but the purpose is narrow enough that the only real invocation choice — fresh vs. polled — is covered.

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 readOnly and closed-world, but the description adds real context: no auth is needed, the data is public, and the winner is deliberately limited to 'display name and time only' — a privacy constraint an agent could not infer from annotations. It stops short of covering freshness, caching, or the shape of the response when no winner exists beyond the `winner|null` hint.

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 resource and its purpose, followed by auth, argument, and return-shape notes in a logical order. The field list is given twice — once in prose and again in the `Returns {...}` signature — which is mild duplication but not costly at this length.

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

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

There is no output schema, so the description carries the full burden of telling the agent what comes back, and it does so with a complete field signature including the nullable winner. Combined with the auth note and zero-arg statement, an agent has everything needed to call and interpret this tool.

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

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

There are zero parameters, so the baseline is 4; the description explicitly says 'Args: none', which matches the empty schema and removes any doubt about required input. Nothing further is needed.

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 (returns the workshop room's public scoreboard) and enumerates the exact contents: enrollment count, skills covered, recipe, manifests, winner, join URL. An agent can distinguish this from ic_workshop_crosstalk_feed or ic_donate without opening any schema.

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

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

The description establishes context by equating the output with the /workshop/live screen, which implies when an agent would want it, and clarifies 'No auth required'. However, it never says when to prefer this over a sibling or what state makes it the wrong choice (e.g. before the workshop opens). Usage is implied rather than directed.

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