Immersive Commons

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

The description discloses the tool makes a server-side web fetch (consistent with readOnlyHint=true), returns a map with empty fields on extraction failure, and specifies supported page types. This goes beyond annotations by detailing the behavior and error handling.

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

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

The description is three sentences with no superfluous words. The first sentence immediately conveys the core action. It uses bullet-style listing in prose, making it clear and efficient.

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

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

Given the tool's simplicity (one parameter, no output schema), the description fully covers what the tool does, what it returns (including fields and empty handling), and supported page types. No other information is necessary 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 single parameter 'url' has no description in the input schema (0% coverage), but the description explicitly mentions 'Args: { url }' and clarifies what kinds of URLs are expected (event pages from Luma, LinkedIn, etc.). This adds meaning beyond the schema's format constraint, though it could specify URI format more explicitly.

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 it performs server-side WebFetch to extract event metadata from a URL, listing specific fields and canonical use cases (Luma, LinkedIn, X, generic OG pages). This specific verb+resource description distinguishes it from sibling tools like floor10_list_claimable_events or floor10_submit_highlight.

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

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

The description explicitly tells the agent to use the returned metadata to compose a HighlightStory, and notes that the tool saves the agent from manual scraping/parsing. This provides clear usage context, though it does not list alternative tools or when not to use, the context is sufficient for this simple tool.

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

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

Annotations already declare readOnlyHint=true. Description adds behavioral context: it confirms token validity and returns specific fields, which is useful 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?

Two sentences, front-loaded with purpose, includes args and return structure. No wasted words.

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

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

Covers purpose, usage, behavior, and return fields. No output schema needed, but the description compensates fully.

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?

No parameters exist; schema coverage is 100%. Per rules, baseline is 4. No additional param info 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?

Explicitly states the tool confirms token validity and returns the scoped floor-member, clearly distinguishing it from other tools like ic_get_my_membership which return different scopes.

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

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

Provides explicit usage context: 'Use as a post-mint smoke check before submitting.' This guides when to invoke it, though it lacks explicit when-not-to-use or alternatives.

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

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

Annotations already declare readOnlyHint=true, so description adds value by stating the data source (graph.yaml attendance ingest, enriched from data/events.yaml) and default behavior of status_filter including invited events for hosts. No contradictions.

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

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

The description is a single paragraph but conveys purpose, usage, source, parameters, and return shape efficiently. Slightly dense but well-organized for the tool's complexity.

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

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

For a list tool with 2 optional params and no output schema, the description provides return type (ClaimableEvent[]) and field details, making it self-contained. Sibling tools are numerous, but this description adequately stands alone.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaning beyond schema by explaining the status_filter default and providing an example (['checked_in','attended'] for 'really went'), enhancing semantics for agent use.

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 returns a list of events for a floor member, with specific verb (returns) and resource (list of attended/invited events). It distinguishes itself by being the auto-discovery layer and mentions use before asking the human, setting it apart from siblings like floor10_submit_highlight.

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: 'Use this BEFORE asking the human what event did you go to?; show them this list and let them pick.' This is clear context-specific guidance, though it does not mention when not to use or name alternative 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=true. Description adds context about the full moderation queue and lack of per-member filtering, which is consistent and provides additional transparency 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?

Extremely concise: two sentences plus a brief specs line. All information is front-loaded and relevant. No waste.

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

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

Given the tool's simplicity (no params, no output schema), the description fully covers inputs, outputs, and usage context. It mentions return shape and limitations.

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

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

No parameters, and schema coverage is 100% trivially. Description mentions 'Args: none,' which is sufficient. Baseline of 4 is appropriate for zero-parameter tools.

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 it returns the count of pending highlight submissions from the full moderation queue. The title and name align, and it distinguishes from list tools like ic_admin_list_pending_highlights by focusing on count rather than detailed list.

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

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

Explicitly describes use case as a backlog probe before adding more highlights. Notes limitations (no per-member filtering, queue is small). Does not explicitly name alternative tools but implies its probe role.

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?

Describes idempotent behavior and rate limits, but contradicts the idempotentHint=false annotation by stating re-submission is idempotent.

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?

Concise, front-loaded purpose, every sentence adds information. No fluff.

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

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

Covers submission rules, idempotency, rate limits, and validation patterns. References external docs. Sufficient for an agent to use 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?

Adds value beyond schema by specifying image ordering, date formats, and action examples. Schema coverage is 82%, so description compensates well.

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

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

Clearly states 'POST a HighlightStory for admin review' and mentions submitting to moderation queue. Differentiates from sibling admin tools like ic_admin_approve_highlight.

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

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

Provides guidelines on idempotency, hard rules for content, and a reference to the REST endpoint. Could be more explicit on when to use alternatives but adequate.

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 claims the tool is idempotent ('same bytes -> same URL'), but the annotation idempotentHint is false. This is a direct contradiction. Otherwise, the description provides useful behavioral details (storage, cache, rate limit, size limits) that go beyond the minimal annotations.

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

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

Three sentences: first states purpose, second details parameters and storage, third adds idempotency, rate limit, types, size, and return fields. No filler, front-loaded, every sentence earns its place.

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

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

Covers purpose, parameters, storage, idempotency, rate limits, allowed types, max size, and return fields. Lacks error handling details (e.g., what happens on rate limit exceed) but is otherwise comprehensive for a file upload tool with 2 parameters and no output schema.

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

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

Schema coverage is 100%, and the description adds significant context: url parameter gets restriction notes (blocked localhost/cloud-metadata), data_url gets use case guidance and overhead explanation. This adds meaning well beyond the schema definitions.

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 re-hosts an image for use in HighlightStory images array, specifies the target storage (IC photo store), and distinguishes two input methods (url vs data_url) with clear recommendations.

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

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

Provides guidance on when to use url (recommended) vs data_url (small local captures), includes rate limits (30 uploads per token per UTC day), and allowed image types. However, does not explicitly contrast with sibling tools like ic_membership_upload_photo or other image 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 provide readOnlyHint=true and openWorldHint=false. The description adds significant detail: the algorithm, fail-closed behavior on tenant-record outage (returns error, never synthesized), and the return shape. No contradiction.

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

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

The description is dense but well-structured with a clear statement of purpose, algorithm, fail-closed note, and return shape. It could be slightly more organized (e.g., bullet points), but every 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?

Given no output schema, the description fully explains the return shape { ok, tenant, tier, available, enabled, force_disabled, effective, breadcrumb } and the breadcrumb format. All necessary information is present.

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?

No parameters exist (schema is empty). The description explicitly states 'Args: none', which is clear. Schema coverage is 100%, so the description adds no extra needed, but it confirms the absence of parameters.

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

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

The description clearly states it resolves the effective feature-module set for the calling token's bound floor, explains the formula (available ∩ enabled) \ force_disabled, and mentions the breadcrumb. This is specific and distinguishes from sibling tools that set features or perform other floor operations.

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

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

It explicitly says 'Read-only; any valid token' and describes the fail-closed behavior, guiding when to use. While it does not name alternatives, the sibling list implies this is the read-only counterpart to setter tools. Clear context for usage.

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

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

Beyond the readOnlyHint annotation, the description discloses that resolution matches the auth gate (no drift), and specifies behavior for tokens without Clerk identity (fail-open public shape). It also notes no scope beyond a valid token and lists the return 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?

The description is concise (4-5 sentences) and front-loaded with the primary purpose. Every sentence adds value: purpose, resolution details, edge cases, and return shape. No redundancy.

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

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

For a read-only introspection tool with no parameters and no output schema, the description fully covers what the tool does, how it works, edge cases, and the return structure. It is complete and sufficient for an agent to understand and invoke the tool.

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

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

The tool has zero parameters, so schema coverage is 100%. The description explicitly states 'Args: none,' which is clear. No additional parameter details 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?

The description clearly states the tool's purpose: 'Introspect the calling token's per-(user, tenant) Floorcast roles on its bound floor.' It uses a specific verb (introspect) and resource (token's roles), and distinguishes itself from sibling tools by focusing on token introspection rather than other actions.

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

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

The description implies when to use (e.g., 'On a token with no tied Clerk identity it returns the fail-open public shape') but does not explicitly state when to use this tool vs alternatives. No mention of when not to use or comparison to siblings.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only' and 'Writes NOTHING'. It adds further behavioral details on the return format and edge cases, which are not covered 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 extremely concise with two sentences, front-loading the key information ('Read-only PREVIEW'). Every sentence adds value without redundancy.

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

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

Given no parameters and no output schema, the description fully explains the tool's behavior, return format, and edge cases. It provides all necessary information for correct invocation.

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

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

There are no parameters, and the schema coverage is 100%. The description correctly states 'Args: none', which is sufficient given the absence of parameters.

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

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

The description clearly states it's a read-only preview of AI-curation output, using specific verbs 'preview' and 'surface'. It distinguishes itself from the sibling tool 'floorcast_run_ai_curation' by emphasizing read-only and preview nature.

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

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

The description explicitly states it writes nothing, indicating safe usage. It also describes when an empty list is returned (static-tier floors, floor10 slug-fenced), providing context for when not to expect results. However, it does not directly mention alternatives like 'floorcast_run_ai_curation' for actual curation.

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

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

The description goes beyond annotations (which only set readOnlyHint=false etc.) by detailing the full return shape for both success (pending vs active status) and failure (typed reasons like forbidden, invalid, approve-failed, tenant-not-provisioned). It highlights the 'CONSEQUENTIAL' nature, policy bypass for free_push_with_retract, and the retraction capability via floorcast_unpush. 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 long but front-loaded with the main purpose. It includes extensive behavioral details, edge cases, and references to other tools. While informative, it could be more concise and structured (e.g., separate sections for behavior, return values, and parameter notes). Still, every sentence adds value and there is no redundancy.

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

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

Given the tool's complexity (11 parameters, nested objects, policy routing, multiple return scenarios), the description covers most essential aspects: push destination, policy defaults, status outcomes, failure reasons, and validation. It references another tool for story shape. No output schema exists, but return values are fully described. Minor gap: no explanation of each parameter's purpose or constraints, but overall complete for agent decision-making.

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

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

Schema coverage is 0% (no parameter descriptions in the schema). The description only vaguely mentions 'Same story shape + validation as floor10_submit_highlight' and 'Args: the HighlightStory fields', without explaining individual parameters or constraints. Given the schema has 11 parameters including nested objects, the description fails to add meaningful semantics beyond what the schema provides.

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

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

The description clearly states the tool pushes a HighlightStory to a floor's MEMBERS WIRE with policy routing. It specifies the verb 'push' and the resource 'floor's members wire', and distinguishes from siblings like floorcast_unpush and floor10_submit_highlight by mentioning policy bypass and same story shape.

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

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

The description explains when to use it (member push) and contrasts the default vs. free push behavior. It mentions that non-floor10 push is currently denied, providing clear context. However, it does not explicitly state when to use alternative tools like floor10_submit_highlight or floorcast_unpush, though the sibling names and context imply relationship.

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 minimal safety hints, but the description adds rich behavioral detail: it assembles candidates from intel, pushes through moderation, handles different floor types (landing pending or error), de-dupes to avoid queue pollution, and returns per-policy results. 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 densely packed with essential information and front-loaded with the core action. While comprehensive, it could be slightly more concise; however, it effectively uses every sentence to convey necessary details.

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

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

Given the tool's complexity (floor types, policies, moderation, dedup), the description covers most behavioral aspects but lacks detail on the exact structure of the per-policy result list. With no output schema, this omission limits completeness.

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 zero parameters and 100% schema coverage, the baseline is 4. The description redundantly states 'Args: none' but adds no new meaning beyond the schema, which is acceptable.

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's action: 'Manual fire of the floor's AI-curation runner' with specific verb ('run') and resource ('AI curation'). It distinguishes from siblings like 'floorcast_preview_ai_curation' by emphasizing this is a commit action, and the title further reinforces the purpose.

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 context on when to use (manual fire) and when not to (static floors, floor10), along with authorization requirement (Floor-Admin gated). It does not explicitly name alternatives but implies differentiation from preview and policy-setting 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?

Adds value beyond annotations by detailing authorization gate, write failure handling, exact error responses, and success return shape. No contradiction with idempotentHint=true or destructiveHint=false. Implementation detail 'inc-6 writer' provides extra transparency.

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?

Single paragraph of 6 sentences is efficient and front-loaded with main purpose. Dense but no unnecessary words. Could be slightly improved by breaking into bullet points or separating 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?

Covers authorization, input structure, error cases, success response, and scope. With no output schema, the description adequately explains return format. All necessary context for a 1-parameter non-destructive write tool is present.

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 covers 100% of parameters, but description adds the internal structure of each policy object (type enum values, optional enabled/max_items) and clarifies maxItems=16 constraint. This supplements the schema's minimal description.

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

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

Clearly states the verb 'sets' and the resource 'AI-curation policy list', and explains it drives the floor's AI self-updating wall. Differentiates from siblings like floorcast_preview_ai_curation and floorcast_run_ai_curation by focusing on setting the policy list.

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

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

Specifies authorization requirement ('Floor-Admin') and describes forbidden response for non-admins. Indicates this tool is for setting policy that drives AI curation. Does not explicitly compare with alternatives, but context from sibling names helps.

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

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

Beyond annotations (idempotent, not destructive), the description adds the full auth gate logic, error response shapes for forbidden and write-failure, and the successful return format. This provides essential behavioral context for safe invocation.

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

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

The description is a single dense paragraph with every sentence adding value: purpose, auth, errors, note on kill-switch, and args. Efficient and front-loaded.

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

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

The description covers auth, error modes, and return format without an output schema. It does not list the concrete module IDs (schema only says 'one of the 8 enum modules'), leaving a small gap for 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 coverage is 100% with descriptions for both 'module' and 'available'. The description only mentions the args without adding new detail or clarifying the module ID enum values, so it adds no extra semantic value.

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 sets which modules a floor is allowed to enable, targeting Super-Admin with apex flag on the same floor. It distinguishes from potential siblings by noting the 'force-disable kill-switch' is not exposed, and the title reinforces the action.

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

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

The description explicitly states the security gate (apex flag, same floor) and provides a clear 'when not to use' by noting the force-disable kill-switch is intentionaly not exposed. However, it does not directly compare to the sibling tool 'floorcast_set_feature_enabled'.

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

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

Annotations are sparse (idempotentHint=true), but description adds rich behavioral details: persistence, authz gate, specific error responses (forbidden, write-failed), and no 500. No contradictions.

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?

Description is comprehensive but slightly verbose. Front-loaded with core action, then details. Could trim minor redundancy, but overall efficient.

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

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

No output schema, but description fully explains return values (success, errors) and side effects (floorcast_effective_features update). Complete for the tool's complexity.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds value by mentioning that module is one of 8 enums (not in schema) and the availability precondition, improving clarity.

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

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

The description clearly states the action (toggles a module in the floor's ENABLED set), the resource (module enabled set for a floor), and the precondition (module must be AVAILABLE). It distinguishes from sibling tools like floorcast_set_feature_availability.

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?

Specifies the target user (Floor-Admin) and precondition (module must be available). Does not explicitly contrast with alternatives, but 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 do not indicate destructiveness, but the description labels the action as 'CONSEQUENTIAL' and explains server-side ownership checking and possible refusal reasons. This adds behavioral context beyond the annotations.

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

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

The description is information-dense but not overly long. Every sentence serves a purpose: action description, limitation, routing, consequential warning, output format. Could be slightly 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?

Given the simple tool with one parameter and no output schema, the description covers all necessary aspects: what the tool does, preconditions (ownership, pending status), possible return values, and error types. It is complete.

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

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

Schema coverage is 100% with a description for the 'id' parameter. The description adds no new meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states that the tool retracts your own still-pending highlight from the floor's queue, using specific verbs and resources. It also distinguishes from other tools by noting that it cannot retract approved/active items.

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

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

The description explicitly states when not to use the tool (for already-approved/active items) and mentions that an operator is needed for those cases. It does not name a specific alternative but gives clear exclusion criteria.

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

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

Beyond the readOnlyHint annotation, the description adds that events include token attribution, success/error status, and detailed fields, providing useful context about what the tool returns.

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

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

The description is two sentences, front-loaded with the main purpose. It is informative but slightly verbose with the enumeration of event types; still clear and efficient.

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

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

Given no output schema, the description provides a good summary of the event fields and the use case, making it complete enough for a list tool with one parameter.

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

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

The single parameter 'limit' is fully described in the schema and reinforced in the description with default and max values, adding clarity 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 it returns recent activity events for the calling user, listing specific event types and the event structure, distinguishing it clearly from sibling tools like administrative audit logs.

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 mentions the use case for auditing one's own agents, but does not provide explicit guidance on when not to use or compare to alternatives like admin audit search.

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

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

Annotations declare readOnlyHint=true, and the description adds rich behavioral context: the search algorithm (walks clients → tokens → threads → actions), ordering (newest-first), pagination details, and scope limitations. 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 a single paragraph that efficiently covers purpose, algorithm, scope, parameters, and return format. It is front-loaded and wastes few words, though the parameter listing could be seen as redundant with 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?

For a read-only search tool with 7 parameters and no output schema, the description explains the search logic, pagination (total, has_more, offset), and filtering options. It is sufficiently complete for an agent to understand usage, though error handling and rate limits are not mentioned.

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

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

Schema coverage is 100% with all parameters described. The description adds context by explaining how parameters like client_id and kind fit into the search algorithm, and clarifies the return format. This goes beyond the baseline 3.

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

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

The description clearly states the tool performs a 'cross-member audit search over class-B integration activity', specifying the verb 'search' and the resource 'class-B integration activity'. It distinguishes from siblings like ic_admin_agent_client_list by focusing on audit of actions across members.

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 notes operator-only access, required scope 'admin:agent_clients', and that counterparty-side actions are out of scope. It provides context on when to use (for auditing class-B integration) but does not explicitly contrast with sibling tools, though no direct alternative exists.

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

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

Discloses operator-only, secret hashes never returned, and caveats about missing stats. This adds value beyond the readOnlyHint and openWorldHint annotations, with no contradictions.

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?

Concise, front-loaded with main action. Includes necessary details about scope, returns, and missing fields. Slightly wordy but still efficient.

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

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

Complete for a list tool with no output schema. Explains return shape, pagination, operator scope, and field limitations. Covers all information needed 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 coverage is 100%, so baseline 3. Description mentions include_revoked and pagination defaults but adds minimal new meaning beyond the schema descriptions.

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

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

Clearly states it lists provisioned class-B integrations with usage stats, newest-first. Distinguishes itself from sibling register/revoke tools by focusing on listing and operator-only access.

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?

Specifies operator-only and required scope admin:agent_clients. Mentions pagination defaults and the absence of certain stats. Does not explicitly state when to use vs alternatives, but the context is clear enough.

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

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

The description provides extensive behavioral details beyond the annotations: operator-only, scope restrictions (only agent:* family), secret returned exactly once, hash storage, denied_scopes listing, and refusal of admin:* scopes. This adds significant value beyond the minimal 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 somewhat lengthy but each sentence adds unique value. It is front-loaded with the core purpose and provides a logical flow: what it does, restrictions, behavior, and return format. Could be slightly more concise but remains clear.

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

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

Given the complexity of the tool, the description is complete. It explains the return format (ok, client_id, client_secret_once, client), the one-time nature of the secret, and the scope denial behavior. No output schema is present, so the description adequately covers what the agent needs to know.

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 coverage is 100% for the parameters listed in the schema. The description adds meaning by explaining the purpose of each parameter (e.g., contact for revoke decision, scopes limitations). However, there is a minor inconsistency: the description mentions 'autonomy?' and 'budget_overrides?' as optional args but they are not in the input 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 title and description clearly state the purpose: 'Register a class-B agent-client integration (operator)'. The description specifies the verb 'Provision' and the resource 'external integration', and distinguishes from sibling tools like ic_admin_agent_client_list and ic_admin_agent_client_revoke.

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

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

The description explicitly states it is 'Operator-only', requires scope 'admin:agent_clients', and mentions a 'live operator-tier re-check'. It provides context on when to use (registering external integrations) and hints at limitations (secret returned once). However, it does not explicitly mention when not to use or suggest alternatives.

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

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

Description reveals key behaviors beyond annotations: revokes all bearer tokens for immediate death, snapshots prior state for revert, and returns counts of flagged actions and revoked tokens. 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?

Description is dense but well-organized: purpose, side effects, idempotency, return value, scope, and args are all covered efficiently. Slightly long 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, description explicitly lists return fields (ok, actions_flagged, tokens_revoked). Covers all critical aspects for a destructive admin tool: scope, side effects, idempotency, and design 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% with descriptions. Description adds minimal extra info (client_id format cli_<base32>), but schema already explains each parameter adequately.

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

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

Description uses specific verb 'Revoke' and resource 'class-B agent-client integration', clearly distinguishing it from sibling tools like ic_admin_agent_client_list and ic_admin_agent_client_register.

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

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

States operator-only scope, idempotency, and that it revokes integrations and flags autonomous actions. Implicitly tells when to use (revoke) versus other actions, but lacks explicit when-not-to-use guidance.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description adds rate limiting, dry-run behavior, side effects (cleaning stale pointers), and scope requirements. 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?

Somewhat verbose but every sentence adds value. Front-loaded with core purpose and logically organized. Could be slightly more terse, but clarity is not sacrificed.

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 covers return shapes for both modes, prerequisites, side effects, rate limits, and idempotency. Comprehensive for a complex mutation 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?

Despite 100% schema coverage, the description adds crucial context: explains id as draft slug from list_pending_events, and confirm as dry-run toggle with rate limit exemption. This significantly aids agent understanding.

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 it approves a pending 'save the date' event draft, specifies the action (flows into approved, drops from pending, writes audit), and distinguishes from creating a Luma event. It contrasts with sibling tools like ic_admin_reject_event by focusing on approval.

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 explains when to use (approve pending drafts), when not to (does not create Luma events), and the two-step dry-run vs confirm process. Idempotency and rate limits are clearly stated, providing full guidance for correct invocation.

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

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

Beyond annotations, the description details the operational effects (dedupe, cap, archive, audit) and idempotent behavior for missing/expired IDs. No annotation contradiction.

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

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

Two sentences, no redundancy. First sentence delivers the core action and side effects; second covers idempotency. Very efficient.

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

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

For a single-parameter tool with no output schema, the description covers the action, effects, and edge cases (missing/expired). Missing explicit return structure but adequate given simplicity.

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 covers 100% of parameters with description. The description adds that 'id' is the submission slug, providing slight extra context. Baseline 3.

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

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

The description clearly states the tool promotes a pending highlight to the live wire with specific behavior (dedupe-prepend, keep 4 active, spill older to archive, drop from queue, audit). It distinguishes from siblings like reject and list.

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

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

The description mentions idempotency and scope (admin:highlights_review) but does not explicitly state when not to use or alternatives (e.g., reject for rejection). The context is adequate for inferred use.

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

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

Annotations declare idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds critical behavioral context: the two-phase dry-run, the fact that the plaintext key appears only on the first mint, that the key works only against IC->Z.ai gateway with zero IC tool scopes, and the rate-limit specifics. It also states the required scope (admin:llm_keys). This exceeds the information provided by annotations alone.

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 well-organized. It front-loads the primary action, then explains the two-step process, idempotence, key scope, rate limits, and parameter details. Every sentence serves a clear purpose with no redundancy. The structure is logical and easy to follow.

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

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

Given the tool's complexity (two-step, idempotent, rate-limited, specific scope) and the absence of an output schema, the description fully covers what an agent needs: behavior, parameters, return shape, and prerequisites (e.g., using request_id from list). It also notes the required scope and rate-limit exclusion for dry-runs.

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% (all three parameters described). The description adds meaning beyond the schema: it explains that omit/false confirm means dry-run, that multiplier is for member keys only, and that request_id comes from the pending list. However, the schema already documents these with similar descriptions, so the added value is moderate. Score 4 reflects clear extra context without being essential.

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 approves a pending key request and mints a proxy key. The verb 'approve' and 'mint' specify the action, and the resource (key request) is unambiguous. It distinguishes itself from sibling tools like ic_admin_deny_key_request by mentioning approval and minting.

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

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

The description provides explicit guidance on the two-step dry-run/confirm workflow, idempotent behavior, and rate limiting (20 approve+deny per day). It mentions the prerequisite source of request_id (from ic_admin_list_pending_key_requests) and notes that dry-run and idempotent re-approvals do not count toward the rate limit. This effectively tells the agent when and how to use the tool.

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

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

The description adds significant context beyond annotations: idempotent behavior ('re-approving an existing owner, or a missing/expired id, is a clean no-op'), additive nature, no displacement, and response structure on missing/expired ('ok:false only on missing/expired'). Annotations already declare idempotentHint=true and destructiveHint=false, which the description confirms and enriches. No contradictions.

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 lengthy but each sentence adds essential information: main action, multi-owner nuance, idempotence, return shape, and scope. It front-loads the core purpose. While it could be slightly more concise, there is no wasted text given the complexity of the operation.

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 explicitly states the return fields: '{ ok, id, slug, founder_clerk_user_id, current_owners }'. It also specifies the required scope ('admin:ownership_review'). For a multi-owner, additive, idempotent tool, this provides a thorough understanding of behavior and results.

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

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

Schema coverage is 100% and includes descriptions for each parameter. The description adds value by explaining that 'confirm' and 'force' are deprecated/no-op and why ('additive approve never needs it'). It also clarifies that 'id' is the pending ownership request id. This goes beyond what the schema provides.

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

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

The description clearly states the verb 'Bind the requesting founder onto the StartupProfile' and explains the resulting action: 'drop the request from the queue, write the active-ownership index + an audit entry'. It also describes the effect on permissions: 'Once bound, that founder's agent/session may edit the page + post news'. This distinguishes it from sibling tools like ic_admin_reject_ownership and ic_admin_list_pending_ownership.

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

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

The description explains when to use the tool by highlighting the multi-owner additive nature: 'approving ADDS the requester to the owner set (the first owner becomes the primary founder_clerk_user_id, each subsequent one is appended) — NO existing owner is ever displaced'. It also clarifies that confirm/force are no-ops. However, it does not explicitly state when NOT to use it (e.g., reject situations), though it implies the context.

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

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

Goes beyond annotations: explains dry-run behavior, rate limit distinction, and that 'operator' tier is approvable despite not being self-requestable. Adds value beyond readOnlyHint and idempotentHint.

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?

Efficiently packed with essential information: purpose, two-step workflow, rate limits, parameter descriptions, return shapes, scope. No fluff.

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

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

Covers all necessary context for a mutation tool with dry-run: workflow, rate limits, return shapes, scope. No output schema but return shapes are described. Complete for the complexity level.

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

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

Adds meaning beyond schema: explains tier override behavior, notes that 'operator' is allowed here, clarifies reason is audited, and details confirm behavior. Schema coverage is 100% but description enriches.

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 'Approve a pending tier request and set the user's tier' and distinguishes from sibling tools like deny and list. It explains the dry-run vs confirm pattern, making purpose 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 describes the two-step workflow and rate limiting. Mentions required scope. Lacks direct comparison to alternatives like deny_tier_request, but provides sufficient context.

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

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

Discloses destructive nature (mutates on confirm), idempotency (refuses to deny already-approved), dry-run behavior, rate limit, scope requirement, and return shapes. 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?

Five well-structured sentences, front-loaded purpose, each sentence adds unique value (purpose, effect, flow, constraints, args/returns). No redundancy.

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

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

Covers all critical aspects: mutation, preview mode, error handling, rate limits, scope, return shapes. No output schema needed given the return description.

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

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

Schema coverage is 100% with good descriptions; description adds context on the two-step workflow and rate limit impact but does not significantly enhance parameter 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 it denies a pending key request, specifies the effect (marked denied, removed from queue, no key minted), and distinguishes from related tools like approve and revoke.

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 describes the two-step process (dry-run vs. confirm), warns against denying already-approved requests with an alternative action, and details rate limits (20 per token per UTC day, dry-run not counted).

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

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

The description discloses key behaviors beyond annotations: it clears pending fields, leaves user tier unchanged, records reason in audit log shown to requester, rate-limit details, and scope requirement. No contradiction with annotations (idempotentHint consistent with dry-run and one-time effect).

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 highly concise with four sentences, front-loading the purpose. Every sentence adds essential information without redundancy, earning a top score.

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 provides return shapes for both call types, rate limits, scope, and behavioral details. It is complete for the tool's complexity and context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that reason is surfaced to requester and confirm controls dry-run vs mutation, enriching the schema's basic descriptions.

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 denies a pending tier request using specific verb and resource. It distinguishes the action (deny vs approve) but does not explicitly differentiate from sibling tools like ic_admin_deny_key_request, though the resource (tier) is clear from the name.

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

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

The description provides explicit guidance on the two-step process (dry-run with confirm=false, actual mutation with confirm=true) and mentions rate limits and scope. It lacks explicit when-not-to-use or alternatives (e.g., approve), but the context is sufficient for a deny action.

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

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

Annotations already mark readOnlyHint=true. Description adds details about returned aggregation errors and freshness, and clarifies private contributions are counts, not repo content. No contradictions.

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?

Description is dense but well-organized, front-loading purpose and then detailing output. Could trim some parentheticals, but efficient overall.

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; description fully documents return structure ({ok, generated_at, stale, age_min, member_count, members, errors}). Covers scope, output, and use case comprehensively.

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?

Single parameter 'limit' is fully described in schema (type, min, max, description). Description doesn't add meaning beyond 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?

Description clearly states 'Operator-only deep read of the commits leaderboard snapshot' and enumerates returned data (ranked board, errors[], freshness). Distinguishes from sibling ic_leaderboard_get_board (likely non-admin) via operator-only scope.

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

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

Explicitly states 'Operator-only' and required scope 'admin:leaderboard_review', and explains use case (spot broken tokens). No explicit exclusions or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, but description adds details: default returns 25 summaries, full mode for export, filter behavior (AND), sort order (newest first), required scope, and response structure. Provides rich behavioral context 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?

Description is 3-4 concise sentences, front-loaded with main purpose and default behavior. No wasted words; every 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, description explicitly states return structure ({ok, count, total, scanned, filter, records}). Covers pagination, filters, default behavior, and required scope. Complete for a 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?

Schema covers 100% of parameters with descriptions, but description adds context like 'Filters AND together', 'Pass full=true to get full records', and explains default pagination. Adds meaningful usage 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?

Description clearly states it reads the agent-voice queue, distinguishes it from sibling tools like ic_admin_resolve_feedback. The verb 'Read' and resource 'agent-voice queue' 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?

Description implies usage for listing feedback with filters and full mode, but does not explicitly state when to use this over alternatives like ic_admin_resolve_feedback. Lacks explicit when-not-to-use guidance.

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

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

Beyond readOnlyHint annotation, description explains it's the actual roster, includes pending_request, resolves from Clerk, and details pagination behavior (filters apply to page, total is full count).

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?

Well-structured: starts with core purpose, then sibling distinction, then return fields, then args, then pagination. No wasted sentences.

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

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

Despite no output schema, description enumerates all return fields (user_id, name, email, tier, pending_request, created_at) and explains pagination and required scope.

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?

Adds meaning beyond schema: explains q is case-insensitive subtitle, limit default 200, offset default 0, and that filters apply to fetched page not overall. Full coverage.

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 it lists all Clerk-backed IC accounts with their live ring/tier, and contrasts with ic_directory_search and curated kiosk list, making its purpose unambiguous.

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

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

Explicitly says when to use (to answer 'who are the members' or find a specific account) and distinguishes from sibling tools (ic_directory_search, curated list). Also explains filters and pagination.

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 provides extensive behavioral details beyond the annotations (readOnlyHint: true), including the exact return structure for pending records and audit entries, the two data sources, and the required scope. 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 front-loaded with the main purpose, then provides structured details. It is packed with information but remains readable. Minor redundancy could be trimmed, but overall efficient.

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

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

For a tool with 2 optional parameters and no output schema, the description fully covers purpose, usage guidance, parameter details, return format, data sources, and required permission. It is complete given the context.

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

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

Although schema coverage is 100%, the description adds valuable context for both parameters: it explains 'detail' as a response weight with concrete effects ('summary' trims rows) and describes 'audit_tail' default and maximum. This goes beyond the schema descriptions.

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 lists pending event drafts awaiting approval, distinguishes it from sibling tools like ic_admin_approve_event and ic_admin_reject_event, and specifies the two sources feeding the queue. The verb 'List' and resource 'pending member-event-request drafts' are specific and unambiguous.

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

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

The description explicitly instructs to 'Use BEFORE ic_admin_approve_event / ic_admin_reject_event' and explains the audit tail for recent decisions. However, it does not explicitly state when not to use this tool or mention alternative tools for other admin review tasks.

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

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

Beyond readOnlyHint, the description details the data returned and the effect of the detail parameter, plus filtering behavior (excludes test fixtures). Fully consistent 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?

Concise, front-loaded with purpose, no wasted words. Every 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 lists return fields and explains the detail parameter, making it complete for a list tool. Scope is noted as 'admin:highlights_review'.

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

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

Schema coverage is 100%, but the description adds value by explaining the default 'full' and what 'summary' trims, providing context beyond the schema's enum and description.

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

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

The description clearly states the tool lists pending highlight submissions with specific fields (id, member, action, event title, date, dek, image count) for review, distinguishing it from sibling approve/reject tools.

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

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

Explicitly pairs with ic_admin_approve_highlight and ic_admin_reject_highlight, and mentions exclusions (test fixtures, stale pointers). Could be improved by stating when not to use (e.g., for approved items), but adequate.

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 provide readOnlyHint=true. The description adds value by detailing the return structure (pending queue + audit tail) and field list, but does not contradict annotations or add behavioral warnings beyond read-only.

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

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

Two sentences plus a structured field list. Front-loaded with main purpose, highly efficient, and no wasted words.

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

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

Even without an output schema, the description thoroughly explains the return value and its fields. Given the tool's simplicity and annotations, it provides all necessary context for correct usage.

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

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

Tool has no parameters; description explicitly states 'Args: none'. Since schema coverage is 100% and there are no params, the description adds no additional meaning, earning baseline 4 for zero parameters.

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

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

The description clearly states it returns the operator's pending Z.ai-key-request queue plus a recent audit tail, specifying the record structure. It distinguishes from sibling tools like ic_admin_approve_key_request and ic_admin_deny_key_request.

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

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

Explicitly says 'Use BEFORE ic_admin_approve_key_request / ic_admin_deny_key_request' and specifies the required scope 'admin:llm_keys', providing clear when-to-use and prerequisites.

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

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

The description adds significant behavioral context beyond the readOnlyHint annotation, such as clarifying that 'already_owned' is informational (not a conflict) and explaining multi-owner behavior. It also specifies required scope (admin:ownership_review).

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 concise (one paragraph) and front-loaded with the purpose. It efficiently packs field details and usage notes, though a structured list might improve readability slightly.

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 fully documents return fields, multi-owner nuances, and required scope. It covers all necessary context for a simple 0-parameter 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% (0 parameters), so baseline score of 3 applies. The description does not need to add parameter info but provides detailed output field documentation.

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 it lists pending founder-binding requests for operator review. It specifically mentions the return fields and explicitly pairs with related tools (ic_admin_approve_ownership / ic_admin_reject_ownership), distinguishing it from 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 is explicit about the tool being for operators ('Operator review queue') and mentions pairing with approval/rejection tools. It explains multi-owner semantics but does not explicitly state when not to use it or provide 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 indicate readOnlyHint: true, so the description adds value by specifying the required scope 'admin:tier_review' and detailing the structure of returned records. It does not contradict annotations and provides additional behavioral context beyond what is in annotations.

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

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

The description is three sentences, each earning its place: first sentence states overall purpose, second details record structure, third provides usage guidance. It is front-loaded with the core function and concise.

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

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

For a zero-parameter read-only tool with no output schema, the description is comprehensive: it covers purpose, structure, usage context, and required scope. It lacks details on ordering or pagination, but those are not critical for this tool's simplicity.

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

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

The input schema has zero parameters and 100% schema description coverage, so the baseline is 3. The description merely restates 'Args: none,' adding no new meaning beyond what the schema already conveys.

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

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

Description explicitly states it returns the pending-membership queue and audit tail, specifying the verb 'Returns' and the resource. It differentiates from sibling tools ic_admin_approve_tier_request and ic_admin_deny_tier_request by indicating it should be used before them.

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 usage context: 'Use BEFORE ic_admin_approve_tier_request / ic_admin_deny_tier_request to see who's waiting and why.' This guides the agent on when to invoke this tool relative to its siblings.

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

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

Annotations already declare readOnlyHint=true, matching the list behavior. The description adds value by disclosing that hidden profiles still surface their rows, a key behavioral detail 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 concise (4-5 sentences) and well-structured: purpose, definition of 'recent', output format, pairing, parameters, and required scope. No extraneous 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?

The description covers the return shape and row fields despite no output schema. It includes required scope. Lacks pagination details, but given the simplicity, it is adequately complete.

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

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

Schema coverage is 100% for the single parameter days. The description adds meaning by explaining the default value (7) and the definition of 'recent' (posts within days or profile edited window).

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

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

The description clearly states the verb 'list' and the resource 'recent startup news items' with a specific use case: 'for the auto-publish safety net'. It distinguishes itself from sibling tools like ic_admin_takedown_startup_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?

The description explicitly pairs the tool with ic_admin_takedown_startup_content, indicating a workflow. It provides context for when to use (reviewing recent content) but does not explicitly state when not to use it.

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

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

Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds critical details: does NOT publish, records audit entry, requires scope admin:events_review, and differentiates rate limit impact for dry-run calls. No contradictions.

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

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

The description is information-dense and well-structured, but slightly long. Every sentence adds value, yet could be more concise without losing clarity.

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

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

For a 3-parameter tool with no output schema, the description covers purpose, workflow, idempotency, rate limits, required scope, and return shapes. It leaves no major gaps for an agent to understand 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?

With 100% schema coverage, the description adds meaningful context for each parameter: id is 'draft slug', reason is 'moderator note' recorded in audit log, confirm switches from dry-run to actual mutation and affects rate limit counting. This goes beyond the schema descriptions.

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 ('Reject') and resource ('pending member-event-request draft'), clearly distinguishing it from sibling tools like ic_admin_approve_event. It explicitly states the action on a 'save the date' draft.

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

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

The description explains the two-step dry-run vs confirm workflow, mentions idempotency, and notes rate limits for mutations only. It does not explicitly compare to other reject tools (e.g., ic_admin_reject_highlight) but provides sufficient context for when to use this tool.

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

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

Annotations already indicate destructive and non-read-only behavior. Description adds that it writes an audit entry and does not publish, providing useful behavioral context 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?

Two short, focused sentences with no fluff. Each word 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?

For a simple tool with good annotations and full schema coverage, the description is complete. It explains the action, side effect (audit entry), and scope.

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 both parameters well-described in the schema. The description adds no new meaning beyond restating the optional reason.

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

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

Description clearly states the action ('Drop a pending highlight'), resource ('from the moderation queue'), and distinguishes it from publishing. Sibling tools like ic_admin_approve_highlight confirm differentiation.

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

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

Indicates scope ('admin:highlights_review') and explicitly says 'Does not publish,' guiding when not to use. No explicit alternatives, but context from siblings is clear.

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

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

Annotations already provide destructiveHint=true, readOnlyHint=false, idempotentHint=true. The description adds that it drops a request and writes an audit entry, aligning with these hints. It does not contradict annotations. However, it lacks details like whether the action is reversible or triggers notifications. The addition of audit trail is useful but not extensive.

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 brief and includes essential information: action, parameters, return shape, and required scope. However, it redundantly lists parameters in the text when the schema is present. Could be more concise by omitting the explicit 'Args' 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?

Given no output schema, the description provides the return shape '{ ok, id, slug? }' and mentions required scope. It covers the key inputs, outputs, and behavioral effects. However, it does not explain post-action effects like notifications or whether the request is permanently deleted. For a simple rejection, it is fairly complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description restates 'Args: { id, reason? }' but adds no new semantic meaning beyond what the schema already provides. The schema already describes 'id' and 'reason' adequately, so the description adds minimal value.

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

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

The description clearly states the action: 'Drop a pending founder-binding request from the queue (no bind) with an optional reason, and write an audit entry.' It uses specific verbs ('drop', 'reject') and resource ('pending founder-binding request'). The title 'Reject a founder-binding claim' also clarifies purpose. This distinguishes it from sibling tools like ic_admin_approve_ownership.

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

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

The description implies usage for rejecting a pending ownership request and specifies required scope 'admin:ownership_review'. However, it does not explicitly state when not to use or compare with alternatives like ic_admin_approve_ownership. The sibling list includes many admin tools, but the description could be more explicit about context.

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

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

Discloses two-step mutation control, dry-run preview, idempotency, and error_kind 'already_resolved'. Requires scope 'admin:feedback_review'. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Five well-structured sentences with front-loaded purpose. Every sentence adds value: purpose, two-step process, idempotency, arguments, return shapes, required scope. No fluff.

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

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

For a mutation tool with no output schema, the description fully explains return shapes (dry-run vs. {ok, record}) and error case (already_resolved). Complete for agent to invoke 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% with descriptions. Description restates parameters and adds contextual value (e.g., dry-run behavior for confirm, note for 'shipping in v1.18'). Adds meaning beyond schema beyond baseline.

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

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

Description begins with 'Mark one ticket resolved with an optional note,' which is a specific verb+resource. It clearly distinguishes from sibling admin tools (e.g., ic_admin_approve_event, ic_admin_list_feedback) by focusing on resolving feedback tickets.

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 describes the two-step process (dry-run vs. confirm), when to use confirm, and idempotent behavior for already-resolved tickets. Provides clear context but doesn't explicitly mention alternatives like ic_admin_list_feedback.

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 claims idempotency ('Idempotent (removing an already-gone item / hiding an already-hidden profile returns ok:true)') but the annotations set idempotentHint: false. This is an annotation contradiction, reducing behavioral transparency to 1. Otherwise, the description provides good detail on side effects (rebuilds cards, mirrors, revalidates, writes audit) and irreversibility.

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

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

The description is a single well-structured paragraph that front-loads the main action, then explains conditional modes, side effects, idempotency, irreversibility, and finishes with args and return summary. Every sentence adds value with no wasted words.

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

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

Despite no output schema, the description includes the return shape and required scope (admin:content_review). It covers side effects, idempotency, irreversibility, and conditional behavior, providing a complete picture for an agent to use the tool correctly.

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

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

The description adds significant meaning beyond the schema: it explains the conditional behavior of item_id (present vs absent), the purpose of reason (moderator note for audit log), and the role of slug. With 100% schema coverage, the description enriches every parameter.

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

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

The description clearly states what the tool does: 'pull auto-published founder content.' It distinguishes two modes based on the presence of item_id: removing a single news item or hiding the whole profile. This differentiates it from sibling admin tools like approval or listing tools.

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

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

The description explicitly explains when to use each mode: with item_id to remove a news item, without to hide the entire profile. It also notes idempotency and irreversibility of news item removal. However, it does not explicitly compare to alternatives or state when not to use it, though sibling context makes the purpose clear.

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

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

Annotations already declare readOnlyHint=true; the description adds context that the result is a hint, not authoritative, and details the return fields (inbox_status, accepted_intents).

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?

Concise, well-structured description that front-loads the core purpose and usage, with no superfluous content.

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

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

The description is complete for a read-only search tool with 2 parameters and a simple return structure, including required scope and behavioral caveats.

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

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

Schema coverage is 100%, but the description adds semantic context: query length constraints (2-80 chars), limit default/max (20/50), and the meaning of return fields beyond their names.

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 it searches the member directory for addressable IC members, annotated with inbox_status and accepted_intents, distinguishing it from the sibling ic_directory_search 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?

Explicitly states it's a routing hint for avoiding closed inboxes before sending meeting requests, and notes that closed-inbox members are still returned so the agent knows they 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?

The description claims idempotency ('re-blocking an existing entry is a no-op success'), but the annotations set idempotentHint=false. This is a direct contradiction. The description otherwise provides useful behavioral details (silent drop, audit logging, self-ownership), but the contradiction invalidates trust.

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 comprehensive but slightly long. It is front-loaded with the main action and each sentence adds unique information. Could be slightly more concise, but structure is clear.

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

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

Given the lack of output schema, the description covers required scope, side effects, idempotency, and return shape. It explains ownership and audit. Missing some details on return fields ('blocklist', 'changed'), but overall thorough.

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. The description adds value by specifying exclusivity of operator/member/client and explaining that reason is recorded in audit only. This goes beyond the schema descriptions.

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

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

The description explicitly states the action ('Add an entry to YOUR inbox blocklist') and the effect ('Future envelopes from a blocked sender are silently dropped'). It clearly distinguishes from sibling tools like unblock or list_blocks. The title reinforces the purpose.

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 guidance: specify exactly one of operator/member/client, and notes idempotency. It explains when the tool is used (before policy rules) and the effect (silent drop). However, it does not explicitly state when not to use it or compare with alternatives like unblock.

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

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

The description adds behavioral context beyond annotations: the privacy mechanism of returning a 404-shape error to unauthorized callers, the structure of returned data (thread, envelopes, actions), and the authorization requirement. Annotations already declare readOnlyHint=true, which is consistent.

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 concise and well-structured: it starts with the purpose, then authorization rules, privacy behavior, argument format, return structure, and required scope. Every sentence adds important information without redundancy.

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

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

Despite no output schema, the description explains what the tool returns (ok, thread, envelopes, actions). It covers authorization, privacy, parameter format, and required scope. For a tool with a single parameter and clear behavior, this is complete.

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

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

The description mentions the parameter thread_id with its shape and source, but this does not add substantial meaning beyond the input schema, which already describes the parameter with the same constraints. With schema coverage at 100%, the description adds minimal extra value for parameter understanding.

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

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

The description explicitly states that the tool returns the full thread record, every envelope, and the audit-action log. This is a specific verb+resource combination. The name 'get_thread' is distinct from sibling tools like 'ic_agent_inbox_list_threads' (which lists summaries) and 'ic_agent_inbox_reply' (which sends a reply).

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 clearly specifies who can call the tool (recipient or original sender) and what happens if unauthorized (404, no leak). It also mentions the required scope 'agent:inbox:read'. While it does not explicitly compare to list_threads, the context is sufficient for an agent to decide when to invoke this tool.

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

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

Adds valuable behavioral context beyond readOnlyHint: empty array when no blocks, return structure {ok, count, blocklist}, required scope. Fully informs agent about operation side effects.

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 efficient sentences, front-loaded with main purpose, no wasted words.

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

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

Though no output schema, description fully covers return value shape and edge cases. Complete for a simple list tool with annotations.

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?

No parameters, and description explicitly states 'Args: none'. With 100% schema coverage and no parameters, baseline 4 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?

Description clearly states it returns blocklist entries, specifies entry types (operator, member, client), and indicates caller-scoping. Distinguishes from sibling mutation tools like block/unblock.

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 when to use (get your blocklist), but does not explicitly exclude alternatives or provide when-not-to guidance. Simplicity of tool reduces need for extensive guidelines.

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 significant context beyond annotations: caller-scoped, member_id from token, agent can only see operator's inbox, sorted by updated_at desc, required scope. The readOnlyHint is already present, but the description reinforces and details behavioral traits without contradiction.

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

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

Concise three-sentence description: first sentence states main purpose and sorting, second explains scope and usage, third lists parameters and return shape. Each sentence is valuable and no wasted words.

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

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

Given no output schema, the description explains the return shape ({ok, count, threads}), sorting, scoping, and usage guidance. For a list tool, this is complete and provides all necessary context for an agent to decide when to use 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?

Both parameters have schema descriptions (100% coverage). The description restates defaults and max, adding marginal value. It also explains return shape but does not enrich parameter semantics further. 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 clearly states the tool returns the calling member's own inbox threads sorted by updated-at descending. It specifies the scope (caller-scoped, operator inbox only) and explicitly distinguishes it from the sibling 'ic_agent_inbox_get_thread' by recommending usage before that tool.

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

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

Provides explicit guidance: 'Use this BEFORE ic_agent_inbox_get_thread to find what's new.' This directly positions the tool within a workflow and differentiates it from a sibling. It also implies the tool is for discovery before detail retrieval.

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 thoroughly explains the state transitions (accept→CONFIRMED, etc.), error conditions, that it is a write operation (readOnlyHint=false), and that the actor member_id is taken from the token. Annotations are consistent and description adds significant behavioral context 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 front-loaded with the core purpose and decision options, then provides state machine details, error conditions, parameter summary, return shape, and scope. It is informative but slightly dense; could be more concise, but every 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?

Given no output schema, the return value is described briefly (ok, envelope_id, new_state). The description covers state machine, errors, authorization (scope requirement), and parameter details. It is sufficiently complete for an agent to understand usage and behavior.

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

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

Schema coverage is 100% with each parameter described. The description adds further context, e.g., for decision enum it specifies the state transitions and that proposed_windows should be included for meeting_request counter. 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 it is for acting on a thread as a party, listing specific decisions (accept/decline/counter/clarify/withdraw) and how they affect thread state. It is distinct from siblings like ic_agent_inbox_send_envelope which also writes envelopes but has different purpose.

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

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

The description explicitly states that the caller must be a thread party, and lists error conditions (not_a_party, thread_terminal, invalid_for_state). It does not provide an explicit alternative tool for different actions, but the constraints are clear enough to guide appropriate usage.

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

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

Discloses behavior beyond annotations: sanitization, persistence, policy evaluation, silent blocks with opaque responses. No contradiction with annotations (readOnlyHint=false).

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?

Well-structured with clear sections and bullet points. Slightly verbose but all content is valuable. Could be trimmed slightly but not wasteful.

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 10 parameters, multiple intents, and security constraints, the description covers everything: return shape, idempotency, precheck, anti-spam, blocking behavior. No output schema but return described.

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?

Every parameter has detailed description adding context to schema: body length limits per intent, consent requirement, idempotency key usage. Schema coverage is 100%, description enhances it significantly.

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

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

Clearly states the verb 'Route' and resource 'typed intent to another IC member's agent inbox'. Distinguishes from siblings like ic_agent_inbox_reply by focusing on sending envelopes.

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

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

Provides explicit guidance: precheck with ic_agent_directory_lookup, idempotency key usage, intent-specific requirements (e.g., consent_target_has_opted_in for send_intro). Explains when it fails (inbox closed) and silent blocking.

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?

Description claims idempotent operation, but annotations set idempotentHint to false, creating a direct contradiction. This misleads the agent about the tool's behavior.

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

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

Concise and well-structured: purpose, constraint, idempotency, owner, args, returns, scope. No redundant information, front-loaded key points.

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

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

With no output schema, the description provides return structure. Covers required scope, ownership, and idempotency. Complete for the tool's complexity.

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

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

Schema coverage is 100% (each param has description). The description adds the crucial constraint that exactly one must be specified, improving semantic clarity 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?

Clearly states the action (remove an entry from inbox blocklist) and resource (blocklist). Distinguishes from sibling tools like ic_agent_inbox_block and ic_agent_inbox_list_blocks.

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 constraint (exactly one of operator/member/client) and mentions idempotent behavior. Does not explicitly state when not to use or mention alternatives, but the context is sufficient.

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 have no contradictions; description adds details about restoring prior state, clearing the window, and writing an audit row, 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?

Description is dense but well-structured, front-loading purpose, then gating, behavior, and returns. A bit long but every 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?

With one parameter and no output schema, the description specifies return fields and replication semantics, making it complete for its complexity.

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

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

Schema covers 100% of parameters, but description adds value by specifying format (act_<base32>) and source (from get_thread's actions).

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 reverses reversible auto-actions (auto-accept/auto-decline) within a window, using specific verbs and resources. It is distinct from siblings like block or get_thread.

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

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

The description provides clear gating conditions (action must exist, thread party, active window, recoverable state) but does not explicitly state when not to use or compare to alternatives.

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

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

The description adds scoping details beyond annotations: 'keyed on the token's sha256, so an agent only ever sees threads it started'. It also lists required scope 'agent:inbox:read'. No contradiction with readOnlyHint.

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 concise (6 sentences), front-loaded with purpose, then usage, parameters, and return shape. Every sentence adds value without redundancy.

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

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

Given no output schema, the description includes the return shape { ok, count, threads }. It also mentions required scope. Missing details about thread object shape, but that is covered by the get_thread tool. Adequate for a 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% with descriptions for both parameters. The description restates defaults and max values, adding value by consolidating information, though not adding new semantics beyond the schema.

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

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

The description clearly states it returns threads initiated by the calling agent, with the title emphasizing 'I STARTED'. It explicitly differentiates from ic_agent_inbox_list_threads, which lists threads addressed to you.

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

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

It provides explicit when-to-use guidance: 'Use this to follow up on requests/intros/messages you sent', and suggests the next step tool ic_agent_inbox_get_thread. It also contrasts with the sibling inbox tool.

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

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

Annotations already provide readOnlyHint=true, but description adds meaningful context: default for new members, required scope, and return structure (ok, policy, presets). No contradictions.

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 concise sentences; first sentence states purpose clearly. Every sentence adds value (scope, defaults, return format, scope requirement). No wasted words.

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

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

With no parameters and no output schema, the description fully covers what the tool returns, how it behaves for new members, and the required auth scope. No gaps for a simple read-only getter.

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?

No parameters exist (0 params, 100% schema coverage), so baseline is 4. Description confirms 'args: none' and doesn't need to add parameter details.

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

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

Explicitly states it returns the current inbox policy, listing the specific fields (inbox_status, default action, rules, blocklist, notification prefs). Clearly distinguishes from sibling set tool by naming the action 'read' and referencing the set tool in context.

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?

Describes scope (caller-scoped to member_id) and default behavior for new members. However, it does not explicitly contrast with the set tool or provide when-to-use vs. when-not-to-use guidance beyond the scope constraint.

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

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

Discloses beyond annotations: prior policy snapshotted to 30-day rollback key, required scope, and return shape. Annotations already indicate mutation and idempotency; description adds useful behavioral context.

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

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

Description is packed with information but remains readable and front-loaded with purpose. Slightly long, but every sentence adds value; could separate technical details for brevity.

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

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

Covers all relevant aspects: purpose, parameters with mutual exclusion, rollback behavior, permission scope, return values, and future plans. No output schema exists, so description compensates fully.

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?

Adds value beyond schema by explaining mutual exclusivity of preset and policy, listing preset slugs, and detailing policy structure (inbox_status, default.action, optional fields). Schema coverage is 100%, but description enriches understanding.

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 it sets the user's inbox policy and opens the inbox, with specific verb 'Set' and resource 'YOUR inbox policy'. It distinguishes from sibling tool 'ic_agent_policy_get' and other inbox tools.

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

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

Provides guidance on when to use preset vs policy, emphasizes 'notify-only' as lowest-friction, and explains caller-scoping. Lacks explicit mention of alternatives or when not to use, but context is sufficient.

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

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

Beyond the readOnlyHint annotation, the description reveals a critical behavioral nuance: reachability is scope-derived and does not reflect floor roles, so a tool may appear reachable but still return forbidden. It also explains the 'additional_gate' field and that scopes cannot be added to existing tokens, providing rich behavioral context.

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

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

The description is a single dense paragraph with many clauses and parentheticals. It conveys valuable information, but its structure is not concise or easily scannable; breaking it into shorter sentences or bullet points would improve readability without losing content.

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

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

Despite lacking an output schema, the description fully specifies the return shape ({ count, caller: { scopes }, tools: [...] }) and explains edge cases like the relationship between reachability and roles. It also clarifies the 'additional_gate' field, making the tool's behavior fully understandable without needing extra documentation.

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

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

The input schema has zero parameters, so there is nothing to document. The description explicitly states 'Args: none,' and the schema coverage is trivially 100%. Baseline for zero parameters is 4, and the description confirms the absence without adding unnecessary detail.

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

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

The description clearly states the tool provides an 'in-band capability matrix' listing every registered MCP tool with its description, required scope, minimum tier, and current token reachability. This distinguishes it from sibling tools, which perform domain-specific actions rather than cataloging.

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

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

Explicitly says to use it 'to plan before calling scope-gated tools' and to inform the human about required tiers and scopes. It also notes it's 'available to any valid token — no extra scope', giving clear guidance on access.

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

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

The description discloses important behavioral traits beyond the annotations: data source (Open-Meteo), caching behavior (~10min), identity-free nature, and the full return structure with all fields. Annotations already provide readOnlyHint and openWorldHint, but the description adds valuable context about how the data is sourced and what the agent can expect in the response.

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

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

The description is well-structured: a brief purpose statement, followed by source/cache details, identity note, return shape, and scope requirement. While it is somewhat verbose (listing the entire return schema), every sentence provides valuable information. It maintains a logical flow and front-loads the main purpose.

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 fully specifies the return value structure, source, caching, and required scope. It covers all relevant aspects for an AI agent to understand what the tool does and what it returns. For a simple read-only context tool, it is completely adequate.

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 no parameters, and the description explicitly notes 'Args: none.' With 0 parameters, the baseline is 4, and the description appropriately clarifies that no arguments are needed, eliminating any ambiguity.

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 'Get Frontier Tower SF local weather + time' and description clearly state the specific resource and action. The verb 'Get' combined with the precise location and data types (weather, time) makes the purpose unambiguous. It distinguishes itself from sibling tools which address different domains (events, directories, etc.).

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

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

The description explicitly states 'Args: none' and 'Required scope: context:read', clearly indicating when to invoke it (no parameters needed) and the authorization prerequisite. It also explains that it is identity-free, implying it is suitable for general context queries. However, it does not explicitly mention when not to use it or alternatives among siblings, though the simplicity makes that less critical.

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 transparency about privacy-graded results based on caller tier and required scope, beyond the readOnlyHint annotation, but the read-only nature is already covered.

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

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

Two sentences plus an args summary, front-loaded with purpose, no wasted words.

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

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

Provides sufficient context for a search tool, including tier-based field visibility, but lacks detail on return format or pagination.

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%. Description adds summary of arguments with types and constraints, and mentions case-insensitive substring matching, adding value 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 it searches the floor roster by specific fields (name, display name, GitHub handle, telegram handle, member id), distinguishing it from sibling tools like ic_agent_directory_lookup.

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

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

Provides clear context on when to use (search directory) and details the privacy-graded results by tier, but does not explicitly contrast with alternative search 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?

Discloses that no auth is required, the first call returns a 402 with tiers, and the donation itself is external. Adds detail beyond annotations, though side effects on MCP state are not mentioned (likely none).

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

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

The description is well-structured and front-loaded, but somewhat verbose with detailed HTTP mechanics. Still earns its length by being informative.

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 fully explains return values (tiers, payTo, asset, network, donate URL) and the workflow. Completely adequate for a zero-parameter 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?

No parameters, so the description cannot add meaning beyond the schema. Baseline 4 applies per guidelines.

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 is for donating USDC to Immersive Commons via x402, using specific verbs and resources. It distinguishes itself from siblings like ic_donations_total.

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

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

Provides clear context on when to use (to donate USDC) and explicit steps for the user, including that MCP cannot perform the 402 handshake. Lacks explicit when-not-to-use, but is still effective.

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?

Description adds return fields and public nature beyond annotations. No contradictions.

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

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

Two sentences, efficient, front-loaded with key 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?

Covers all necessary information for a simple read-only endpoint with one optional parameter.

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?

Fully documents limit parameter with range and default, compensating for 0% schema coverage.

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

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

Clearly states it returns running total, donor count, and recent donations. Distinct from sibling 'ic_donate' which is for making donations.

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 no auth required and that it's the public donor wall data. Could improve by contrasting with ic_donate.

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 provide readOnlyHint and openWorldHint. The description adds important context: it only searches the upcoming-events cache, returns 404 if not found, and requires scope events:read_upcoming. 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 two sentences: the first states the purpose, the second adds constraints and parameter details. It is front-loaded, efficient, and contains no unnecessary 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?

Given the simple nature of the tool (single parameter, no output schema, clear annotations), the description covers everything needed: what it does, cache behavior, error condition, and required scope. It is fully sufficient for agent selection and 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 coverage is 100% and the schema already describes the 'luma' parameter. The description merely restates the URL format. It adds minimal extra meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states it finds an event in the upcoming-events cache by Luma URL, which is a specific verb+resource. The title also explicitly says 'Look up a single IC event by Luma URL'. This distinguishes it from sibling tools like ic_events_list_upcoming or ic_events_get_live.

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

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

The description implies when to use (cache lookup) but does not explicitly state when not to use it or mention alternatives. It notes the cache limitation and scope requirement, but lacks direct comparisons to similar 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?

Discloses read-only nature (readOnlyHint), heuristic time window, known cache limitation, returns null if no event, and required scope. 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?

Efficiently packs critical info: time window definition, heuristic disclosure, null return, usage guidance, and required scope. No wasted words.

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

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

Covers purpose, usage, logic, and scope. Lacks explicit output structure but mentions slideshow_url/metadata, which is adequate given no output schema.

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

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

No parameters (empty schema), so baseline 4. Description adds server-side current time context, which is helpful.

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

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

Clearly states returns the currently in-progress IC event with a specific time window (when <= now < when + 3h). Distinguishes from sibling tools like ic_events_get and ic_events_list_upcoming by focusing on the live event.

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 to use when an agent needs 'what's happening right now' for slideshow_url/metadata. Does not explicitly list alternatives but context implies not for past/future events.

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

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

Beyond the readOnlyHint annotation, the description details the caching mechanism (hourly Luma sync), response features (stale flag, age_min), required scope (events:read_upcoming), and parameter limits. This equips the agent with critical behavioral and usage constraints.

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 extremely concise: two sentences covering purpose, backend, response, and parameters. Every sentence adds value, and the structure front-loads the main function, followed by technical details.

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 lacking an output schema, the description fully informs the agent about what the response contains (stale flag, age_min) and the cache behavior. For a simple read-only tool with one optional parameter, no additional context is necessary.

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