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?

The description goes well beyond annotations by detailing the dry-run behavior ('mutates nothing'), the side effect of promoting and indexing, the idempotent outcome ('returns ok:false' when nothing pending), and separate return shapes. This provides rich operational context that the annotations alone do not convey.

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

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

The description is dense but well-organized, starting with the core action, then the two-step behavior, idempotency, args, returns, and scope. Every sentence adds value without redundancy, making it appropriately sized for the tool's complexity.

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

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

With no output schema, the description compensates by specifying the return shapes for both confirm false and true. It covers the core operation, side effects, error case, and required permission, making it complete for an operator approval tool within this family.

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

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

Schema already documents both parameters with 100% coverage, serving as a baseline. The description adds useful context by linking endpoint_id to ic_admin_list_pending_endpoints and explicitly explaining the confirm flag's role in the two-step process, going beyond the schema's straightforward 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's purpose: 'Approve the card awaiting review on an endpoint' and specifies the outcome ('promotes it to the served card and indexes it for ic_endpoint_search'). This specific verb+resource combination distinguishes it from sibling approval tools like ic_admin_approve_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?

It explains the two-step workflow via the 'confirm' flag, describing dry-run versus apply behavior. It also identifies the source of endpoint_id using ic_admin_list_pending_endpoints and the required scope (admin:endpoints_review). However, it doesn't explicitly contrast with alternative approval tools beyond referring to 'the other operator queues', so it falls short of full when-to-use/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?

The description goes far beyond the destructively false annotation by revealing critical behavioral details: the Meshy credit cost, 34-minute time cost, the fact that generationsUsed is never refunded automatically, the writing through a quota record, and the grantLog audit entry. It also clarifies that delta must be 1..25 and that a failed run still burns allowance.

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 in the first sentence. It packs rich context into a compact paragraph. However, it is slightly verbose with some explanatory asides (e.g., 'by design: a failed Meshy job still billed') that could be shortened without losing meaning.

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 has 3 parameters, 100% schema coverage, and no output schema, the description is quite complete. It explains the business domain (Meshy credits, 34 min per figure, free allowance), the mutation semantics (writes through quota record, audit log), and the required scope. It slightly loses a point for not explicitly stating what happens if an invalid handle is provided or whether the delta can be negative (though delta schema shows min 1).

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that 'handle' can be a 'funko handle, or their Clerk user id', which is a meaningful clarification not in the schema. The reason parameter is described as landing 'permanently' in the grantLog, adding durability context. The description also explicitly lists the return fields { ok, userId, grants, allowance }, which is very helpful since no output schema exists. Minus 1 because the delta range (1..25) is already in the schema 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 starts with 'Add generation allowance to one member', which is a specific verb+resource combination. It clearly distinguishes this tool from its siblings (like ic_admin_funko_restore and ic_admin_funko_takedown) by focusing on granting extra figure generations versus restoring or takedown 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 explicitly states when to use this tool: 'an operator hands out a re-roll, or makes good after a failed run that still burned the allowance'. It also explains the context of generations being non-refundable and the requirement of 'admin:funko_review (operator)' scope, providing clear guidance on appropriate vs inappropriate 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?

The description adds significant behavioral context beyond the minimal annotations: it overrides the member's own switch, is heavily audit-logged, is refused if the handle has been reassigned, and requires a specific scope. These details compensate for the lack of rich annotation flags.

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 purpose, then covers behavioral notes, refusal condition, arguments, return format, and required scope. Every sentence is necessary and adds value with no redundancy.

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

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

The description covers purpose, behavior, refusal condition, return format, and scope. It is slightly incomplete by not explicitly stating that the figure must currently be in a taken-down state, but this is implied by 'undo.' Overall sufficient for correct agent usage.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description mentions the args but does not add new semantic meaning beyond what the schema already provides. 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 explicitly states the tool is the undo of ic_admin_funko_takedown, sets publicShare=true, and re-lists the handle. It clearly distinguishes from the paired takedown tool and other admin functions like ic_admin_funko_grant by specifying its role as a reversal operation.

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

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

The description indicates it is specifically for reversing a takedown and includes a refusal condition (handle changed hands). It provides clear context for when to use it versus alternatives, though it does not explicitly list 'do not use' scenarios or compare to other sibling tools.

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

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

The description claims idempotency ('IDEMPOTENT') and explains the behavior on retry, but the annotations set idempotentHint=false. This is a direct contradiction. Per the scoring rule, a contradiction warrants a score of 1. Additionally, the description provides rich behavioral detail (reversibility, audit logging, no blob deletion), but the contradiction undermines reliability.

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 about 150 words and front-loads the main action. Every sentence adds value, but it is slightly verbose. It could be shortened without losing clarity, but it remains well-structured and 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?

The description is very complete for a mutation tool with destructive effect, idempotency, reversibility, audit logging, and no output schema. It covers side effects, prerequisites, alternatives, and return fields. No gaps are evident.

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

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

The schema covers both parameters with 100% description coverage. The description adds minor context: handle accepts handle or Clerk user id, and reason is a moderator note for audit log. This aligns with the schema descriptions, so the description adds limited value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Take a published figure out of public view' and explains the specific effects (sets publicShare=false, removes from gallery index, returns not_found). It distinguishes itself from the sibling tool ic_admin_funko_restore by noting this is reversible and not a deletion.

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

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

The description explicitly tells when to use this tool (to unpublish a figure) and when not to use it ('If you need the bytes actually gone, this tool is not that'). It also directs to the alternative (ic_admin_funko_restore) and mentions required scope (admin:funko_review).

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?

Beyond the annotations (readOnlyHint=true, openWorldHint=false), the description discloses ordering ('Newest first'), defaults ('newest 25 summaries'), preview truncation ('first 200 chars'), filter semantics, resolved tri-state, and required admin scope. It also states the exact return shape { ok, count, total, scanned, filter, records }, giving an agent full behavioral expectations.

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 efficient; every sentence carries distinct operational information. It is front-loaded with the core purpose, then defaults, full mode, filter semantics, return shape, ordering, and auth scope. There is no filler or redundant restatement of schema content.

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

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

Given six optional parameters and no output schema, the description compensates by covering defaults, pagination-related limit/offset behavior, filtering semantics, full vs. summary mode, return object shape, ordering, and auth requirement. An agent has enough information to call the tool correctly and interpret its response.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: 'full=true' is labeled for export/triage, filters are described as AND-ed together, and resolved is explicitly documented as a tri-state (open only, closed only, both). This clarifies how the parameters work in combination rather than just what each one means.

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

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

The description opens with a specific verb and resource: 'Read the agent-voice queue.' It goes beyond the title by defining the object (feedback on agent voice), the default summary view, and the admin scope (admin:feedback_review), which clearly separates it from feedback tools like ic_feedback_list_mine and other admin list tools.

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

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

The description gives clear usage context: default summaries for quick scanning, 'full=true' for 'export / triage', and explains how filters behave ('AND together'). It does not explicitly name a competing tool or say when not to use it, but the workflow guidance is strong enough for an agent to pick it correctly.

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

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

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantial behavioral detail: entries are ordered newest first, the card shown is AWAITING REVIEW (not currently served), and the verification process is described. It also states the required scope (admin:endpoints_review) and return shape, all of which go 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?

The description is well-structured and front-loaded: it states the primary action first, then details the queue contents, explains the context and decision, and finally lists arguments, returns, and required scope. Every sentence earns its place, and the length is appropriate for the 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?

Given the tool has one optional parameter, no output schema, and a clear sibling context, the description is complete. It specifies what the queue contains, what has already been proven, what the agent's judgment should be about, the parameter constraints, the return structure, and the required scope. No critical information is missing.

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

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

The input schema covers the only parameter (limit) with a description and constraints, so the baseline is 3. The tool description merely restates 'max 200, default 50' without adding new semantics. No extra meaning is needed because the schema already documents the parameter effectively.

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

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

The description opens with 'Read the endpoint-registry review queue, newest first,' which uses a specific verb and resource, clearly distinguishing it from sibling list_pending_* tools for events, highlights, key requests, etc. It further specifies that entries show the card AWAITING REVIEW, who registered it, and which origin was mechanically proven, making the tool's purpose unmistakable.

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

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

The description gives clear context for when to use the tool: to review the endpoint-registry queue before deciding whether the service belongs on the floor. It explains that origin ownership is already proven, so the agent knows what the judgment should focus on. It doesn't explicitly name alternatives or list when-not-to-use scenarios, but the context is strong enough for an agent to differentiate.

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), the description explains exactly what is destructive (the in-flight change) and what is not (a live listing stays serving). It also discloses the state transitions, dry-run behavior, return shapes, and required scope. This is rich, non-contradictory behavioral detail.

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

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

The description is dense but well-structured: action, critical caveat, alternative, two-step mechanism, args, returns, scope. Every sentence serves a purpose, though it is longer than ideal. Slightly verbose but not wasteful, so 4.

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

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

With no output schema, the description compensates by detailing return shapes for both confirm values. It also covers permissions, the review context, and alternative actions. The tool is fully contextualized for an agent to use it correctly without further lookup.

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

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

Schema coverage is 100% and each parameter already has a clear description. The tool description adds marginal cross-reference (note being readable via ic_endpoint_get) and confirms optionality of confirm, but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Refuse the card awaiting review on an endpoint') with a specific verb and resource. It also distinguishes from siblings by clarifying it only rejects a pending change, not a live listing, and references alternative tools like unlisting. This is precise 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?

Explicitly provides when-to-use guidance and an alternative: 'To take down a live listing, unlist it instead.' It also explains the two-step dry-run pattern, making the invocation sequence clear. This fully addresses usage context and 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?

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?

Beyond the readOnlyHint annotation, the description discloses substantial behavioral details: closed-inbox members are still returned, scopes are per-token and cannot be added, and this is a routing hint versus the authoritative policy engine. It also explains the tier-gating of send-side scopes and the distinction between inbox_status and addressable_by_you. No contradiction with annotations—much added value.

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 densely packed with critical information. It front-loads the purpose and the crucial warning about reading 'addressable_by_you' early, then details the fields, scope behavior, and output structure. Every sentence serves a purpose; the length is justified by the tool's complexity. It is not merely verbose—it is well-structured, though a bit long.

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 all necessary aspects: purpose, field semantics (both recipient and caller sides), intended usage (which field to read), behavioral caveats (scope minting, routing hint, closed-inbox inclusion), required scope, and a full output schema description. Given the tool's complexity, nothing critical is missing—this is a complete definition.

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

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

The input schema has 100% description coverage for both parameters, providing the exact semantics (query as name fragment, limit bounds). The description merely repeats the same constraints (e.g., 'query: string (2-80 chars)') without adding new meaning. Per the rubric, baseline is 3 when schema coverage is high and description adds no extra context.

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

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

The description clearly states the tool searches the member directory for members you could address, and specifies the resource (floor roster + canonical members) and the dual annotation (recipient posture and caller reachability). It distinguishes itself from generic directory tools by focusing on addressability and scope. This is a specific verb+resource, not a tautology.

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

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

The description gives strong usage guidance: it explicitly instructs to read 'addressable_by_you' rather than 'inbox_status' before planning a send, and explains why. It also notes this is a routing hint, not the authoritative decision. However, it does not explicitly name an alternative tool or state when NOT to use this tool (e.g., for authoritative policy checks), though the policy engine reference implies it. This is clear context but lacks explicit exclusions for a full 5.

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

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

The 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?

Annotations are all false (no read-only, idempotent, etc.), so the description carries the full burden. It discloses server-side sanitization, persistence, policy evaluation (store+notify, queue-for-tap, silent drop, refuse), idempotency caching, the exact return shape, the mcpError on closed inbox, and the opaque silent-block behavior. This is exceptionally transparent for an agent, leaving no hidden 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?

The description is long but well-ordered: purpose, server behavior, scopes, send_intro special requirements, idempotency, return shape, precheck, and a v1 note. Each sentence carries information with minimal fluff. It is not overly verbose given the complexity of 10 parameters and 4 intents, but a future revision could condense the server-side details slightly without loss. Structured and front-loaded with the core action.

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

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

Given 10 parameters, multiple intents, no output schema, and no annotations to lean on, the description is remarkably complete. It explains the return shape, edge cases (blocklist, closed inbox), prerequisites (directory lookup), and per-intent requirements. An agent has everything needed to call this tool correctly. No gaps remain 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?

Though schema coverage is 100%, the description adds substantial meaning: it defines body per intent (≤800 for ping, becomes context_summary for request_meeting, intro_pitch for send_intro), states that send_intro requires intro_target_name + body + expected_outcome + consent_target_has_opted_in=true, and explains idempotency_key's 24h caching. It also clarifies the 'message' intent not mentioned in the main description. This goes far beyond the schema.

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

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

The description states a specific verb ('Route a typed intent') and a clear resource ('another IC member's agent inbox'), enumerating the three valid intent types (ping / request_meeting / send_intro). It differentiates itself from sibling tools like ic_agent_inbox_reply by focusing on sending, not responding. The intent and scope are unmistakable.

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

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

The description provides an explicit PRECHECK ('call ic_agent_directory_lookup first') and explains when the tool will refuse (closed inbox). It also warns that send_intro requires extra params and consent. However, it does not explicitly contrast with sibling tools like ic_agent_inbox_reply (though that is semantically different), leaving the agent to infer when to use this versus a reply. The precheck and per-intent requirements are strong, but an explicit 'when-not-to-use-except-reply' would be clearer.

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 rich behavioral context beyond the readOnlyHint=enable annotation: explains caller-scoped server-side behavior, the union of token and member scopes, the re-minting implication on visibility, and the distinction between thread lifecycle state and delivery/read receipts. It also discloses the lack of delivery confirmation, which is critical for correct interpretation. 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 lengthy but every sentence earns its place: purpose, scoping nuance, limitations, return shape, and required scope. The most critical information (purpose and counterpart) is front-loaded. The density is justified by the tool's complexity, though slight trimming of the re-minting explanation might tighten it.

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

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

For a tool with no output schema, the description provides the return shape ({ok, count, threads}) and required scope (agent:inbox:read). It covers the important caveats (no receipt semantics, scoping subtleties) and gives a complete picture for an agent to invoke correctly. Given the complexity and lack of output schema, nothing essential is missing.

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

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

Schema coverage is 100% (both limit and offset have descriptions including defaults and max). The description repeats these defaults but adds no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the full burden, and the description does not add extra parameter context like paging strategy beyond what's in the schema.

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

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

States a specific verb and resource: 'Returns the threads the calling agent's token initiated' and explicitly distinguishes from the sibling ic_agent_inbox_list_threads (which lists threads addressed TO you). The sender-side counterpart framing makes its role unambiguous among many 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 explicit when-to-use guidance: 'Use this to follow up on requests/intros/messages you sent' and routes to ic_agent_inbox_get_thread for full thread details. It also clarifies what the tool does NOT tell you (no delivery/read receipts) and explains the scoping edge cases (re-minting, class-B clients), helping the agent decide when this tool is appropriate.

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.