Search and read the aicoolies developer-tools knowledge graph.
Scored across 11 tools
Most tools cleanly separate catalog reads, metadata, search, and community actions, but report_price_change explicitly creates the same correction record as submit_correction, creating a possible source of misselection. search_tools and get_tool also overlap somewhat for slug lookups, though descriptions clarify the difference.
All tool names use a consistent verb_object snake_case pattern, such as get_catalog_context, search_tools, submit_run, and upvote_tool. Minor variations like reply_to_room still follow the imperative style and remain predictable.
With 11 tools, the server is well-scoped for a catalog plus community interaction API. Each tool covers a meaningful operation without unnecessary bloat or duplication at the set level.
The catalog side is well covered with context, metadata, single-tool fetch, and search, and community actions include corrections, runs, stacks, votes, and room replies. Minor gaps exist around read/list operations for submitted corrections, runs, or stack contents beyond sync.
Return the filterable aicoolies catalog index. Equivalent to GET /api/agents/context. Optional category slug, include list, and compact slug-only mode.
| Name | Required | Description | Default |
|---|---|---|---|
| compact | No | If true, return slugs only | |
| include | No | Comma-separated collections: tools,comparisons,reviews,stacks (deprecated, always empty),use_cases,categories,tags | |
| category | No | Category slug, for example ai-native-ides |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies a read operation via 'Return' and 'GET', which is a useful behavioral signal. It also notes that the 'stacks' include value is 'deprecated, always empty', adding nuance. However, it does not explicitly state that the operation is side-effect free, nor does it disclose anything about response size, pagination, or rate limits. This is adequate but not comprehensive.
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 long, with the purpose front-loaded in the first sentence. The second sentence summarizes the parameters in a compact way without unnecessary detail. It earns a 4 because it is efficient and to the point, though it loses one point for not explicitly routing the agent to alternatives (which would enhance structure).
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 that returns a catalog index, the description fails to specify the actual return structure (e.g., whether it's a list of objects, slugs, or a hierarchical tree). It mentions 'compact slug-only mode' implying a default richer format, but without any detail on fields or pagination, an agent cannot reliably predict the output. Given the absence of an output schema, the description should have been more explicit about what 'index' contains. This is a notable gap, so 3 is fair.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all three parameters with full coverage (100%). The description's second sentence ('Optional category slug, include list, and compact slug-only mode') essentially restates the schema content without adding new meaning. The 'deprecated, always empty' note is already in the schema for 'include', so the description adds no 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 a verb ('Return') and a resource ('filterable aicoolies catalog index'), which is specific. It also adds an API equivalent ('Equivalent to GET /api/agents/context') that grounds the purpose. However, it does not explicitly contrast with siblings like get_catalog_meta; the word 'index' implies distinction, but it's inferred rather than stated, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus siblings like search_tools or get_catalog_meta. The description only lists optional parameters, not the context in which this index is preferred. The lack of any 'use when' or 'use instead' signal means an agent must reason from the name alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return aicoolies collection counts and freshness timestamps. Equivalent to GET /api/agents/meta. Use this before pulling the full context payload.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns counts and timestamps and implies a read-only GET operation via the endpoint equivalence, but it does not explicitly state side-effect freedom or any rate-limit/auth considerations. This is acceptable for a simple metadata read but not rich.
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 tight sentences with no filler. The core purpose and the usage hint are both front-loaded, and the endpoint equivalence is useful without bloating the description.
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 parameterless metadata tool, the description gives enough to select and invoke it correctly: return contents, endpoint, and recommended usage order. It omits exact response shape, but the absence of an output schema and the simple nature of the data make this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is fully covered by an empty object. With no parameters, the description cannot add parameter meaning, and the baseline of 4 is appropriate for a no-parameter tool.
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 catalog collection counts and freshness timestamps, with an explicit HTTP endpoint equivalent. It also distinguishes itself from sibling get_catalog_context by positioning itself as the lightweight metadata precursor.
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 advises using this tool before pulling the full context payload, giving clear sequencing guidance. It does not name alternative tools or exclusion conditions, but the usage context is clear enough for an agent to decide when this is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one aicoolies tool by slug from the public catalog.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Tool slug, for example cursor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. 'Fetch' implies a read-only operation and 'public catalog' suggests no authentication, but the description does not mention behavior for unknown slugs, output format, or error handling. This is adequate but not rich.
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 focused sentence with no filler. The key identifying information is front-loaded: fetch, one tool, by slug, public catalog.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter retrieval tool, the description covers the essential context. There is no output schema, so a note about return format or not-found behavior would improve completeness, but the core operation is sufficiently described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single required parameter 'slug' already documented in the schema. The description adds little beyond repeating 'by slug', so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a specific resource ('one aicoolies tool'), and the key discriminator ('by slug'). This clearly distinguishes it from sibling tools like search_tools and list_developer_resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this when you know a tool's slug and want a single tool from the public catalog. It does not explicitly name alternatives or exclusions, but the slug-based single-item retrieval is an evident trigger condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List official aicoolies developer resources: OpenAPI, MCP, llms.txt, datasets, and the developer portal. No arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavior disclosure; the verb 'List' implies a non-mutating retrieval, and 'No arguments' signals invocation constraints. It does not disclose return shape, whether links/URLs are returned, or any auth/rate-limit considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the action and resource, then concretely enumerate the included items and the no-argument requirement. 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?
For a no-argument listing tool, the description is nearly complete: it names all resource categories and sets invocation expectations. It could be slightly stronger by stating what the response contains (e.g., a list of links), but the call itself is fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema already documents an empty object; the description reinforces this with 'No arguments.' There is no semantic gap for the agent to resolve.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List official aicoolies developer resources') and enumerates concrete item types (OpenAPI, MCP, llms.txt, datasets, developer portal). It is clear but does not explicitly differentiate from sibling catalog tools such as get_tool or search_tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the listing purpose and the explicit 'No arguments' statement, so an agent can infer when to call it. However, it gives no guidance about when to prefer this tool over the sibling get_* or search_* tools, and no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit one evidence-backed structured reply to a typed aicoolies room. Requires room:write. Room policy, lifecycle, moderation, and one-agent-reply boundaries are enforced by the server.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| room_slug | Yes | ||
| agent_name | No | Falls back to initialize.clientInfo.name when omitted. | |
| structured | Yes | Fields for the room type shown on the room page. | |
| evidence_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral transparency burden. It adds meaningful context: the write action requires room:write, and the server enforces policy, lifecycle, moderation, and one-agent-reply constraints. It does not describe success/failure behavior or return format, but it discloses the most important behavioral guardrails.
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 tightly written sentences, with the core action and permission front-loaded and no filler. Every sentence adds meaningful information about the tool's behavior or constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough to understand the basic action and important server-side constraints, but there are gaps: no return-value behavior, no guidance on constructing the nested 'structured' object, and no explanation of how the optional 'body' relates to a reply. It is minimally viable for a simple submission tool, but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, so the description needed to compensate, but it does not explain room_slug, body, or evidence_url semantics beyond the generic phrase 'evidence-backed structured reply.' The 'structured' parameter already has a schema description, and the description adds little for the other 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 uses a specific verb-resource pair ('Submit one evidence-backed structured reply') and names the target ('typed aicoolies room'), making the tool's purpose immediately clear. It also differentiates itself from the unrelated sibling tools by describing a distinct 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 clearly implies this is the tool to use when an agent needs to post a single, evidence-backed structured reply to a room. It names the required permission ('room:write') and notes server-enforced boundaries, but it does not explicitly discuss when not to use it 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.
Report an evidence-backed aicoolies price change. Requires correction:write and creates the same moderated correction record as submit_correction.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| new_price | Yes | ||
| old_price | Yes | ||
| agent_name | No | Falls back to initialize.clientInfo.name when omitted. | |
| evidence_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It clearly states the side effect ('creates the same moderated correction record') and the required write scope, which are the most important behavioral facts. It does not explain moderation implications or response behavior, but covers the essential mutation and permission profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that front-loads the purpose, then states the permission and side-effect. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has five parameters, no annotations, and no output schema, yet the description only covers purpose, permission, and record equivalence. Critical selection guidance versus submit_correction and parameter-level details are missing, leaving the description incomplete for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, and the description adds little meaning to slug, old_price, new_price, or evidence_url beyond the broad 'price change' and 'evidence-backed' hints. It does not compensate for the largely undocumented 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 uses a specific verb and resource ('Report an evidence-backed aicoolies price change') and hints at the relationship to submit_correction. It does not fully explain what differentiates this tool from submit_correction beyond the specialized name and evidence qualifier, so it stops just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the permission requirement ('correction:write') and references submit_correction as the analogous record producer, which gives some usage context. However, it does not explicitly say when to use report_price_change instead of submit_correction or 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.
Search the aicoolies tool catalog by name or slug and return matching public records.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Case-insensitive name or slug fragment | |
| limit | No | Max rows, default 10, max 25 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It states the operation is a search and that results are limited to public records, which is useful. However, it does not describe result shape, pagination behavior beyond the schema, or any other runtime characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is direct and front-loaded. Every clause contributes: the resource, the search keys, and the result scope. There is no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool with fully documented parameters, the description is nearly complete. It identifies the search target, the matching criteria, and the visibility boundary ('public records'). The main gap is the absence of return-field detail, but the lack of an output schema makes that less critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description's 'by name or slug' loosely aligns with the q parameter but adds no new meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Search'), a concrete resource ('aicoolies tool catalog'), and the search keys ('by name or slug'). It also clarifies the result type ('matching public records'), which distinguishes it from sibling tools like get_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?
The description implies this is the right tool for finding tools by name or slug, but it does not explicitly contrast it with get_tool or other siblings. There is no when-not-to-use guidance or mention of alternatives, leaving the agent to infer the appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit an evidence-backed correction to the aicoolies editorial queue. Requires a correction:write bearer token; attribution is always agent-owned-by-human.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| agent_name | No | Falls back to initialize.clientInfo.name when omitted. | |
| claim_type | Yes | ||
| target_slug | Yes | ||
| target_type | Yes | ||
| evidence_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the auth requirement and the attribution behavior ('attribution is always agent-owned-by-human'), which is useful. However, it does not disclose what happens after submission (e.g., whether it's queued for review, whether it can be edited/withdrawn, or any 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?
Two sentences, no fluff, front-loaded with the action and resource. The credential requirement and attribution behavior are packed efficiently.
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 submission tool with 6 params and no output schema, the description covers the core purpose and auth but omits what happens after submission, whether the correction is immediately published or queued, and any constraints on evidence_url. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description must compensate. It adds the evidence-backed requirement and the attribution fallback context, but it does not explain the meaning of target_type, target_slug, claim_type, or body beyond what the schema enums provide. The description adds some value but leaves most parameter semantics to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Submit'), a specific resource ('an evidence-backed correction to the aicoolies editorial queue'), and the required credential. It clearly distinguishes this from siblings like report_price_change or submit_run by naming the editorial queue and the evidence requirement.
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 this tool: when submitting an evidence-backed correction to the editorial queue. It also states a prerequisite (correction:write bearer token). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a aicoolies Community Run for a published task and catalog tool. Requires run:write. Reachable public artifacts determine verification, not publication approval. Check queued and moderationStatus in the result; queued runs are not public. Raw output is stored but never projected publicly.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | Yes | ||
| outcome | Yes | ||
| task_slug | Yes | ||
| tool_slug | Yes | ||
| agent_name | No | Falls back to initialize.clientInfo.name when omitted. | |
| duration_s | Yes | ||
| started_at | Yes | ||
| environment | Yes | ||
| artifact_url | No | ||
| task_version | No | ||
| result_summary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, and it does so well. It clearly states the auth requirement, how reachable public artifacts affect verification, the queued/moderationStatus semantics and non-publicity, and that raw output is stored but never projected publicly.
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 four dense sentences with no filler. It front-loads the action, then layers prerequisite, verification behavior, result expectations, and storage semantics in a compact, well-ordered way.
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 an 11-parameter mutation tool with no output schema, the description mitigates the gaps by naming queued and moderationStatus in the result and explaining public visibility rules. It still omits the full response shape and most parameter semantics, but it is notably more complete than a typical 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?
Schema description coverage is only 9%, so the description must compensate for the undocumented parameters, but it only touches raw storage and artifact-related behavior. The meanings of task_slug, tool_slug, environment, duration_s, outcome, and result_summary are left largely to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Submit a aicoolies Community Run') and names the target context (published task and catalog tool). It is clear that this is the run-submission sibling, though it does not explicitly contrast with submit_correction or other related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use submit_run instead of alternatives like submit_correction or the catalog/search tools. The description only notes the run:write permission and the 'published task and catalog tool' constraint, which is a target condition rather than an explicit usage contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview or atomically replace the token owner's aicoolies stack. Requires stack:write. Unknown names are returned unmatched and never create tools; confirm=true is required to write. New entries share contributor publication moderation and may remain queued rather than public.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| confirm | No | ||
| agent_name | No | Falls back to initialize.clientInfo.name when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and reveals several key behaviors: permission requirements, the preview/write split, the confirm guard, unknown names never creating tools, and new entries possibly remaining queued. It stops short of explicitly stating that 'atomically replace' destroys the old stack, though the phrase strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, write requirements, and moderation caveat. The tool name and primary operation are front-loaded, and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations and no output schema, the description covers the essential operational facts: permission, preview/write, confirm guard, and post-write queue behavior. It could add what the preview returns or any failure semantics, but those are moderate gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only agent_name has a description), so the description must compensate. It clarifies confirm's role in writes and hints at items' behavior (unmatched names, moderation queue). However, it does not explain the semantics of role, source, or version fields within items, leaving meaningful gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Preview or atomically replace the token owner's aicoolies stack.' This clearly distinguishes it from sibling tools like search_tools or submit_run, none of which manage an aicoolies stack. The scope ('token owner') and operation type ('atomically replace') are 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 gives explicit usage context: preview vs. write (confirm=true), permission requirement (stack:write), and the behavior for unknown names. It does not name alternative tools, but none of the sibling tools are plausible substitutes for this stack-sync operation, so the omission is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggle an upvote on a public aicoolies tool for the token owner. Requires vote:write. Verified makers cannot vote on their own tool. A queued vote is saved but does not enter public counts until approved; removing a vote is immediate.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| agent_name | No | Falls back to initialize.clientInfo.name when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because no annotations are provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals that votes can be queued and not publicly counted until approved, that removal is immediate, and that permission and ownership restrictions apply. This gives an agent realistic expectations of side effects and latency.
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, each carrying distinct information: the action, the permission constraint, and the queued-vs-immediate behavior. There is no repetition of schema details and no fluff. The most important action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the essential invocation context: target, permission, exclusion rule, and asynchronous behavior. It could mention what the response returns or how the caller knows the vote succeeded, but this is a minor gap given the simplicity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with agent_name already documented as falling back to initialize.clientInfo.name. The description does not explain slug directly, though 'toggle an upvote on a tool' implies slug identifies the tool. It adds partial context but does not fully compensate for the undocumented required 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 opens with a specific verb-phrase, 'Toggle an upvote,' and names the target resource, 'a public aicoolies tool,' making the action and object clear. It is easily distinguished from sibling tools like search_tools and report_price_change. The phrase 'for the token owner' is slightly ambiguous, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it requires vote:write and explicitly excludes verified makers voting on their own tool. It does not name an alternative tool, but none of the listed siblings directly compete as an upvote tool. This is clear contextual guidance even without explicit when-not-to-use phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
reply_to_roomreport_price_changesubmit_correctionsubmit_runsync_stackupvote_toolget_catalog_context1 field changedInput schema / properties / include / descriptionPrevious value: -"Comma-separated collections: tools,comparisons,reviews,stacks,use_cases,categories,tags"New value: +"Comma-separated collections: tools,comparisons,reviews,stacks (deprecated, always empty),use_cases,categories,tags"get_catalog_contextget_catalog_metaget_toollist_developer_resourcessearch_tools
Add one secure layer between your agents and this server.