Mockbird

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

With no annotations, the description carries the full burden. It discloses side effects such as auto-creating a project, the seeding behavior (default and max), and the response including new project credentials when auto-creating. It does not detail failure modes or reversibility, but covers key behavioral aspects.

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: it starts with the purpose, then explains the two modes, seed, and auto-creation. The list of field types is lengthy but necessary and directly actionable. No redundant sentences.

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

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

For a complex tool with 6 parameters and no output schema, the description covers the essential usage, including the auto-creation response. It does not explicitly describe the normal response format (e.g., resource id), but given the schema descriptions and the clarity of the operation, it is sufficiently complete for an agent to call it correctly.

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

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

The description adds substantial meaning beyond the schema, especially for the 'fields' parameter by listing all valid types and the 'oneOf' enum structure. It also clarifies the seed defaults and the auto-creation condition for project/adminKey, which are not fully explained 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?

The description clearly states the action: 'Add a resource (collection) to a project and seed it with realistic fake data.' It specifies the resource type and the dual modes (template or fields), which distinguishes it from siblings like generate_fake_data (which likely generates data without adding to a project).

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 when to use the tool, including the two input modes and the auto-creation behavior when no project exists. It gives conditional guidance (omit project and adminKey to auto-create) but does not explicitly mention alternatives like create_project or generate_fake_data, though the usage 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?

With no annotations present, the description carries the full burden and does so thoroughly. It discloses the keyless GET method, 30-minute check frequency, Cloudflare network origin, body-based failure detection, and honest reporting behavior. It also explains the summary vs. single-service detail output, including fields like down_since and 24h/7d uptime.

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 dense and well-structured: scope, method, frequency, no-argument behavior, single-service behavior, and use case all appear in logical order. Every sentence adds practical information, and the examples are illustrative rather than filler.

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

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

For a one-optional-parameter tool with no output schema and no annotations, the description is remarkably complete. It covers authentication, frequency, result contents for both invocation modes, failure semantics, and even expected follow-up guidance when a service is down. Nothing essential for calling the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: the parameter accepts id, name, or hostname substring, gives concrete examples like 'httpbin' and 'reqres.in', and clarifies that omitting it returns the summary. This goes beyond the schema's already good 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 states a clear verb+resource: it checks the live status of ~58 public mock/testing APIs, listing concrete examples like JSONPlaceholder and httpbin.org. It is unambiguous about what the tool does, though it does not explicitly contrast itself with sibling tools such as watch_service_status or uptime_monitor.

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

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

It gives a clear usage context: 'Use it before pointing tests or tutorials at a public API.' It also explains what happens when a service is down, linking alternatives. However, it does not explicitly say when not to use this tool or mention sibling alternatives, so it stops short of full routing guidance.

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

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

With no annotations provided, the description fully carries behavioral disclosure. It reveals the return shape, warns that adminKey is shown only once, explains preset behavior in detail, and documents live API behavior, CORS, auth, and the bundled OAuth2/OIDC provider.

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 almost every sentence carries actionable information about presets, return values, security, or service behavior. It is front-loaded with the core purpose and then expands into necessary operational details, making the length justified.

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, this description is unusually complete: it specifies the returned fields, the one-time adminKey, preset semantics, TTL lifecycle, live endpoint behavior, auth expectations, and the OAuth provider. An agent has everything needed to create and immediately interact with the project.

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 the schema already covers 100% of parameters, the description adds substantial meaning: it explains what each preset seeds, what 'blank' means, what a starter project contains, and how ttl expiration can be extended or canceled via HTTP. This goes well 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?

Opens with a precise 'Create a new mock REST API project' statement that clearly identifies the verb, resource, and tool scope. It is immediately distinguishable from sibling tools like add_resource or fork_project.

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

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

Provides clear guidance on when to use presets, when to omit preset for a starter project, and when to use 'blank'. It does not explicitly contrast with sibling tools such as fork_project, but the context is strong enough for an agent to know this is the entry-point creation 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?

With no annotations provided, the description carries the behavioral disclosure burden. It does well by explaining template expansion variables, raw JSON insertion via triple braces, route precedence, fallback catch-all semantics, and the per-project limit. However, it does not disclose duplicate-route overwrite behavior, error cases, or authorization requirements beyond the implied adminKey.

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 dense sentences with no filler. The core purpose is front-loaded, followed by concrete examples and behavioral constraints. Every clause earns its place by conveying template mechanics, precedence, fallback behavior, or limits.

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 8 parameters and no output schema or annotations, the description is largely complete: it covers the purpose, path syntax, template behavior, precedence, and route limits. Remaining gaps are the lack of return-value explanation, duplicate/overwrite semantics, and any error behavior when the limit is exceeded, which are relevant but not fatal.

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 75%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It explains body template syntax in depth, gives path parameter patterns (:key, *), and clarifies defaults like status/contentType indirectly through examples and route behavior. The only weak spots are project and adminKey, which receive no semantic explanation anywhere.

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

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

The description opens with a specific verb and resource: 'Define a custom endpoint on a project' and gives concrete path examples (/health, /config/:key, /webhooks/*). It also distinguishes custom routes from sibling resource routes by stating that custom routes take precedence over resource routes.

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 context for when to use the tool: for custom endpoints, request bins, and catch-all routes. It includes key routing nuances like precedence over resource routes, '*' fallback behavior, and the 20-route limit, though it does not explicitly say 'use X instead' for 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?

With no annotations provided, the description fully discloses the destructive behavior: 'Permanently delete... Irreversible.' It enumerates exactly what data is affected and states the auth requirement 'Requires the adminKey.' This exceeds expectations for a delete tool.

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 compact and front-loaded with the most critical fact—permanent deletion. Each of the three sentences earns its place: scope of deletion, irreversibility, and usage guidance plus credential 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?

For a simple two-parameter tool with no output schema and no annotations, the description is impressively complete. It covers what is deleted, the irreversibility, when to use it, and the required credential. An agent has everything needed to invoke it correctly.

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

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

The input schema already provides 100% coverage with descriptions for both 'project' and 'adminKey'. The description adds only 'Requires the adminKey.', which slightly reinforces the requirement but adds minimal semantic value beyond the schema.

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

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

The description states the specific verb 'delete' and the resource 'project', and clarifies the scope with 'ALL its data (records, resources, snapshots, custom routes, webhooks, request log)'. It clearly distinguishes itself from sibling tools like create_project and project_info by emphasizing permanent deletion of the entire project.

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 a clear use case: 'Good practice for short-lived test projects: clean up when your session is done.' It also signals caution with 'Irreversible.' Although it doesn't explicitly name alternatives, the guidance is sufficient for an agent to decide when to invoke this destructive 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?

With no annotations provided, the description carries the full burden. It discloses that the fork has its own id and adminKey, that withSnapshots:true copies snapshots as answer keys, and that TTl causes auto-deletion. However, it doesn't explicitly state the resource is a write operation in a sure way, but 'let the agent mutate the fork freely' implies write access. The description is detailed but leaves out explicit reversibility or permission requirements, which are minor for a copy operation understanding.

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 block but dense with useful detail. It is front-loaded with the core purpose and then appends usage scenarios. While it is relatively long (over 150 words), every sentence adds relevant context; it's not redundant. The only minor issue is that the grading note could be more condensed, but overall it is well-structured.

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 (5 parameters, no output schema, no annotations), the description is comprehensive. It covers prerequisites (adminKey for non-demo), side effects (TTL deletion, snapshot copying), and usage patterns (CI runs, demo forking). There is no missing information an agent would need to call it correctly; the absence of an output schema is compensated by the description's mention of 'own id + adminKey'.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the purpose of ttl ('crashed runs can't leak sandboxes') and withSnapshots ('answer keys travel with it'), and clarifies that adminKey is not needed for 'demo'. However, for parameters like 'name' and 'project', it doesn't add much beyond schema descriptions that already name them unambiguously.

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 'Copy an entire project — resources + records verbatim, custom routes, behavior settings — into a brand-new project with its own id + adminKey,' clearly stating the verb (copy) and resource (project). This distinguishes it from siblings like create_project (which creates from scratch) and share_project (which shares existing 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?

The description provides explicit when-to-use context: 'Built for parallel eval/CI runs' and specific instructions like 'keep a template project, fork_project per run with a ttl... let the agent mutate the fork freely, then grade with snapshots action:'diff'.' It also includes conditional usage: 'Works on the shared playground with NO adminKey: {"project":"demo"} gives you the demo dataset as your own private project.' This is exemplary usage guidance.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states that nothing is created or stored, no project or adminKey is needed, and that seeding produces deterministic, reproducible output. It does not mention rate limits or error behavior, but the key side-effect-free nature is transparent.

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 bit long, but each sentence adds meaningful context: statelessness, resource shapes, custom fields, determinism, and the hosted alternative. It could be tightened by removing the repeated type list in prose, but it is not padded with 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?

The description gives enough context for an agent to decide when and how to call the tool, including parameter behavior and the relationship to sibling tools. It does not describe the response format, but since there is no output schema and fake-data output is generally self-evident, this is not a critical 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 input schema already covers all five parameters with descriptions, so the baseline is high. The tool description adds valuable semantics beyond the schema, such as the default resource ('Default persons'), the precedence rule ('Ignored when fields is set'), and concrete examples for fields and params.

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 generates realistic fake data instantly and is stateless, creating or storing nothing. It also names the specific resource types and distinguishes itself from hosted alternatives like create_project and add_resource.

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 explains when to use this tool versus hosted alternatives: 'Need the data HOSTED instead? create_project / add_resource...' This gives clear selection criteria and directs the agent away from the wrong 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It richly describes side effects and lifecycle details: alert fires once plus a recovery message, creation counts as the first ping, id/secret/ping_url cannot be recovered, limits of 5 live heartbeats per IP, deleting frees a slot immediately, and idle pollable heartbeats are removed after 30 days.

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

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

The description is long and dense, but nearly every clause carries essential behavioral information and the core concept is front-loaded. It could be better structured with clear action-by-action formatting instead of one long paragraph, but it contains 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?

Given the tool has five actions, eight parameters, no output schema, and no annotations, the description is remarkably complete. It covers all actions, creation return values, ping usage, poll semantics, info, delete, notify formats, limits, recovery behavior, and cleanup policy. Nothing essential is left for the agent to guess.

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 schema already documents each parameter, but the description adds crucial semantics beyond it: period_minutes range, grace defaulting to half the period, notify omission producing a pollable heartbeat, and the curl usage pattern for ping_url. This makes the parameters genuinely actionable rather than merely named.

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 defines the tool as a 'Dead man's switch' for cron jobs and scheduled tasks, stating that the job pings Mockbird and an alert fires when pings stop. It explicitly distinguishes itself as the INVERSE of uptime_monitor, so an agent can immediately tell the two apart.

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 guidance: use it for recurring jobs that must report in, and contrasts it directly with uptime_monitor. It also distinguishes between webhook-notified heartbeats and pollable heartbeats, and explains when to use ping, poll, info, and delete. The phrase 'use this to arm a heartbeat for YOUR OWN recurring runs' makes the primary use case unmistakable.

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 determinism, no account/expiry/watermark, pre-validation against the real endpoint so a returned URL is guaranteed to render, and the exact return shape {url, markdown}. It also explains live badge behavior (re-counted on every render, ~60s cache), the message-only badge case, hex color conventions without '#', and per-kind format defaults. These are significant behavioral details beyond the schema.

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

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

The description is a dense wall of text with heavy parenthetical chains and inline examples. Every sentence carries real content, but it lacks structural formatting (bullet-like delineation, line breaks per kind) that would aid parsing. The opening sentence front-loads the core purpose well, but the overall structure is cramped for the amount of information it conveys.

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

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

For a complex, param-rich tool with no output schema, the description is remarkably complete: it covers the return format, all six kinds with their parameter sets, format defaults, size conventions, several character limits, and the optional project scoping. It does not mention error behavior beyond the validation guarantee, but that is a minor omission given the breadth of coverage.

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

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

Schema coverage is 100%, so the schema already describes kind, size, format, params, and project. The description adds substantial meaning to the nested params object: per-kind parameter lists, punctuation rules for chart data (commas and pipes), live-mode resource/filter syntax, QR ecc options, and text length limits. It loses a point because the massive per-kind detail is embedded in the description, making it hard to quickly extract a single canonical param list, but it clearly adds value beyond the schema.

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

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

The description names a specific verb and resource: 'Mint a permanent, keyless image URL rendered by Mockbird.' It goes on to enumerate concrete use cases (README badges, charts, QR codes, OG cards, placeholders, avatars) and states the deterministic/never-expires guarantee, which separates it from sibling tools. The main purpose is unmistakable despite the length.

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?

Each kind is paired with a usage context: badges for READMEs (including live record-count badges), charts for data visualization, QR for URLs/WIFI/mailto, og for social meta tags, placeholder for sizing, and avatar for initials. It also says when to use the shared demo project versus passing your own project id, and explains that params can be passed directly as top-level properties for convenience. This is strong practical routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses size limits (512 KB, 8 MB for HAR/cassette), auto-detection behavior, how different formats are handled, seeding defaults, and the exact response shape ({id, adminKey, baseUrl, warnings[], routes[]}). This is highly transparent about what happens when invoked.

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 with a semicolon-separated list of formats. It front-loads the primary purpose and uses specific details. It could be slightly more scannable as bullet points, but it avoids redundancy and every clause contributes information.

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

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

For a tool with 5 parameters, multiple input formats, and no output schema, the description is remarkably complete. It covers format behavior, size limits, seeding, response structure, and even hints at error handling via warnings[]. An agent has enough information to call it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by specifying that 'seed' applies only to OpenAPI specs and 'resource' is CSV-only, which clarifies parameter usage beyond the schema's generic descriptions. It also explains that 'content' can be multiple formats, enriching the meaning.

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

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

States a specific verb and resource ('Create a live mock API from existing artifacts') and enumerates supported formats (OpenAPI, Swagger, json-server db.json, Postman Collection, HAR, VCR, bare JSON, CSV/TSV). This clearly distinguishes it from siblings like create_project or generate_fake_data, which are about creation/generation rather than importing.

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 it (when you have existing artifacts) but does not explicitly name alternatives or exclusions. However, the format list and behavior make the intended usage clear, and it differentiates from siblings by focusing on importing rather than building from scratch.

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

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

With no annotations, the description carries full responsibility, and it delivers: authorization redaction, body snippet limitation to writes, retained-window semantics, per-run fork isolation, segment-aware path matching, and admin/auth exceptions for the demo project. This exceeds what a typical tool description discloses.

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 (purpose first) and every sentence serves a purpose: verification, companion tool, trajectory assertion examples, per-run isolation, and auth. It is dense but not bloated; its length is justified by the lack of structured annotations or an output schema. Slight redundancy in participant examples like 'DELETE' and 'status_gte:400' could be trimmed, so not a perfect 5.

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 thoroughly explains what is returned (fields listed, redaction, body snippet), how the log relates to episodes ('fork per run'), the retained window, and auth requirements. An agent has enough to call it correctly and reason about its results without additional lookups.

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?

Even though the schema already covers all 100% of parameters, the description adds meaningful usage context: filters return a {count} of matches, they are for trajectory assertions, since should capture episode start, and demo requires no adminKey. This adds value beyond the bare 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 identifies the tool's action and target: 'Read the project's request inspector' and describes precisely what is returned (method, path, query, status, origin, headers, body snippet). It also specifies the intended use—verifying what clients actually sent—which distinguishes it from siblings like query_records or project_info without ambiguity.

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

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

It gives an explicit when-to-use ('Use it to VERIFY what your app / tests / webhook sender actually sent') and a concrete workflow: point code at the mock, run, inspect. It also mentions pairing with custom_route for webhooks. It does not name alternatives or exclusion cases, so it gets a 4 rather than 5.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly indicates this is a read/retrieval operation ('Get') and spells out the response contents in detail, including export links and auth mode. It also discloses the authorization requirement ('No adminKey needed'). It does not explicitly state that no mutation occurs, but the content and framing make that sufficiently clear.

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 compact and front-loaded, with the core purpose stated first, followed by a detailed list of return contents, then a concise note about authorization and a practical example. Every sentence earns its place and there is no filler.

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

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

For a single-parameter, no-output-schema tool, the description fully explains what the agent will get back: resources, counts, URLs, routes, auth mode, and export links. It also covers access requirements and gives a concrete suggested value. 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 description coverage is 100%, so the schema already documents the single 'project' parameter as the project id. The description adds the useful example of 'demo' as a public playground, but does not substantially extend parameter meaning 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 opens with a specific verb and resource ('Get a project's public root index') and then enumerates exactly what that index contains: resources with record counts and URLs, custom routes, auth mode, and export links. It clearly distinguishes itself from sibling mutation tools like create_project/delete_project by stating no adminKey is needed and emphasizing the public, informational 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 gives clear context for when this tool is appropriate: it is a public, read-only operation requiring no adminKey, which implicitly contrasts with admin-requiring sibling tools. The suggestion to 'Try project demo for the shared public playground' provides a concrete usage example, though it does not explicitly name alternatives or 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?

With no annotations present, the description carries the full burden — and it delivers: discloses pagination defaults (_limit=25, max 100 per page), fixed vs. random latency semantics, deterministic failure sequencing for retry tests, random chaos injection, and response-envelope wrapping. Exceptional disclosure for a mock tool.

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?

Highly dense single paragraph, but every clause carries unique semantic weight and the core read behavior is front-loaded before the mock controls. The mock parameters would read easier as a bulleted list, yet there is no filler or 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 4-parameter tool with no annotations and no output schema, the description is complete: required vs optional params are clear, the param grammar is exhaustively specified, and defaults/limits are stated. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 75% and the project parameter is undocumented, but the description massively overcompensates: it documents the entire params-object DSL with concrete operator signatures (price_gte, date_lte, name_like, status_ne), sorting/pagination keys, the select projection syntax, relation expansion, and every mock-control parameter with exemplar values.

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 'GET records from a mock resource' — a specific verb plus resource that immediately identifies the operation. The read orientation is clearly distinct from siblings like write_record and import_data, letting an agent route correctly without inspecting any sibling schemas.

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 comprehensive query-grammar documentation (filters, operators, sorting, pagination, projection, relations) leaves no ambiguity about how to construct read requests. It does not explicitly name alternatives or state when-not-to-use, though the GET verb and the write-natured siblings make the boundary obvious.

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 the schema: read-only access, no adminKey exposure, works in protected mode, and the semantics of each action (create returns existing link, rotate invalidates old, revoke kills, status reports). This is substantial behavioral context. However, it doesn't mention rate limits, idempotency details beyond create, or what happens if the project doesn't exist. With no annotations, the description carries the burden, and it does well but not perfectly.

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. It front-loads the core purpose and key constraint, then provides workflow guidance, then action semantics. It's a bit long but every sentence adds value. The only minor issue is that the action semantics could be more structured, but it's 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 the tool's complexity (4 actions, security implications, workflow integration), the description covers the essential context: what the link does, how to use it in an agent workflow, and what each action does. It lacks an output schema, so it doesn't describe the return format (e.g., shareUrl field), but the description mentions shareUrl, which helps. It could also mention error cases, but overall it's quite 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%, so the schema already documents all parameters. The description adds meaning by explaining the action enum values (create, rotate, revoke, status) and their effects, which goes beyond the schema's simple 'Default: create.' It also clarifies that project and adminKey are required. This is a solid addition, though the schema already covers the basics.

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: mint or manage a read-only share link for a project. It specifies the resource (project), the action (share link), and the key behavioral constraint (read-only, no adminKey exposure). It also distinguishes itself from siblings by focusing on sharing for human review, which is unique among the listed 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 provides an agent workflow: build or mutate a sandbox, then share_project and give the human the shareUrl. It also explains when to use it (after building/mutating, for human review) and what it does in protected mode. It doesn't explicitly name alternatives, but the workflow guidance is strong and the tool's unique purpose 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?

With no annotations, the description carries the full burden. It discloses that snapshots are deterministic, restore is exact, and diff returns a structured result ({identical, summary, resources[]}). However, it does not explicitly state the side effects of restore (overwriting live data) or delete, or any authorization requirements. These are significant for a mutation-capable tool.

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 then elaborates on diff and mock usage. While it is longer than two sentences, every sentence adds value—no fluff or repetition of schema details. The structure could be tightened, but it remains readable and focused.

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 (7 parameters, multiple actions, nested data), the description covers the major concepts: snapshot naming, diff grading, and read-only serving via mock_snapshot. It doesn't mention error handling, permission prerequisites, or the exact behavior of restore beyond 'exact', but the coverage is adequate for an agent to understand how to use 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?

Schema description coverage is 57%, so the description must add meaning. It explains the diff action's return structure and the mock_snapshot query param usage, which complement the schema's per-parameter notes (data, name, ignore, against). It also clarifies the workflow for authoring inline data. This goes beyond the schema's plain 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: saving, restoring, diffing, listing, and deleting project dataset snapshots. It uses specific verbs and a resource ('project's entire dataset'), and it distinguishes itself from siblings by framing snapshots as deterministic test fixtures and eval grading rather than live data 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?

The description provides concrete usage scenarios: authoring answer-key snapshots, grading via diff, and serving GETs from snapshots via mock_snapshot in query_records. It explains the diff workflow and parallel test scenarios, but it doesn't explicitly state when to avoid this tool or name alternative tools that might be better for live operations.

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

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

With no annotations, the description carries the full burden and fully delivers: 30-minute polling, 8s timeout, 2xx/3xx semantics, same-run retry, debounced two-check confirmation, one message per transition, webhook signing, 3-per-IP limit, 30-day expiry, and irrecoverable id/secret. It discloses both destructive and rate-limit 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?

The text is long, but nearly every sentence carries operational detail and the action-by-action structure makes it scannable. It would benefit from line breaks, but there is little wasteful prose.

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

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

There is no output schema and no annotations, yet the description explains result contents, status page/badge/feed, webhook message shapes, polling behavior, and limits. An agent has everything it needs to invoke the right action and interpret responses.

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 substantial semantic value: notify format detection for Slack/Discord, signed JSON for other endpoints, what omitting notify means, and that id/secret are returned by create and cannot be recovered. This goes well beyond the schema's terse parameter 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 identifies a concrete service: monitoring public URLs with create/poll/info/delete actions, and it explicitly contrasts itself with the inverse heartbeat tool. The action labels and their effects make the resource and behavior 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?

It explicitly names the alternative for cron/scheduled contexts ('use the inverse tool: heartbeat') and explains when to choose notify versus pollable monitors. Action-specific requirements, such as create needing url and poll/info/delete needing id+secret, are spelled out.

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

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

There are no annotations, so the description carries the full behavioral burden. It discloses the last-50 request window, the mutual exclusivity of inline spec vs saved spec, the need to author the snapshot first, and the admin-key-free share-link path. It does not explicitly state whether the call mutates state or is read-only, but the workflow strongly implies evaluation-only 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?

Information-dense and for the most part well-sequenced (definition → usage → saved-spec mode), but the first sentence packs several concepts together and the block is somewhat dense for an agent to parse quickly.

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 the full operational context: authoring snapshots, trajectory examples with count semantics, the 50-request log window, the fork-per-run pattern, saved specs, and the share-link auth model. Practically all behaviors an agent needs to invoke this correctly are in the 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?

The schema already describes each parameter, and the description adds critical usage detail: how snapshot interacts with the snapshots tool, how trajectory constraints are shaped, and how name resolves to a saved spec. The ignore parameter is named but not expanded in the prose; however, the schema carries that weight.

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 identifies the tool's purpose: produce a single pass/checks verdict from a state diff and trajectory constraints. It differentiates the tool from sibling operations (snapshots, projects) by framing it as the verdict step in a fork → act → verify → delete harness.

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 concrete workflow guidance: fork a project, run the verdict with snapshot and/or trajectory, assert pass, then delete. It also explains when to pass a snapshot name vs. raw inline data deme, and how saved specs plus share links work for graders without an admin key.

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

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

No annotations are provided, so the description carries full burden, and it delivers rich detail: debouncing across two consecutive hourly checks (blips never fire), immediate confirmation message, HMAC-signed JSON for non-Slack/Discord webhooks, native payloads for Slack/Discord, hourly polling cadence, 5 live watches per IP with immediate slot release, and the need to store both id and secret.

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: it leads with the core purpose, then organizes the actions explicitly (action:'subscribe', action:'poll', action:'info', action:'unsubscribe'), then covers notify formats and limits, and ends with a pointer to the sibling. No filler sentences.

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

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

For a multi-action tool with no annotations and no output schema, the description is unusually complete: it covers all actions, return values ({id, secret}, events, state), webhook formats, debouncing, rate limits, and alternatives. An agent can invoke it correctly without additional information.

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 meaningful context beyond the schema: it explains that service is an id from check_api_status or '*', that notify can be omitted for a pollable subscription, and that id/secret must be stored. It doesn't fully describe the semantics of action beyond the enum, but the schema already covers that.

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 clear verb ('Subscribe to down/recovered alerts') and explicitly names the resource (public mock/testing APIs tracked by check_api_status) with concrete examples. It also distinguishes itself from the sibling uptime_monitor by stating 'To watch YOUR OWN URL instead, use uptime_monitor.'

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 this tool vs the alternative: it is for public mock/testing APIs, while uptime_monitor is for your own URL. It also details four actions (subscribe, poll, info, unsubscribe) with clear conditions, including when to omit notify for a pollable subscription.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses important side effects—persistence and per-method behavior (auto-id, replace, merge, delete)—which is substantial. It does not cover return values or error behavior, but the core mutation semantics are transparent.

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

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

Three dense sentences convey scope, persistence, and method-specific rules with no filler. The most important behavioral contrast—writes persist—is front-loaded, and 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 5-parameter mutation tool with no output schema, the description covers method semantics well but omits guidance on valid project/resource identifiers and expected response format. These gaps prevent full standalone usability, though the core CRUD workflow is understandable.

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 real meaning to method by explaining what POST, PUT, PATCH, and DELETE do, and it clarifies when id is required. However, project and resource, two required parameters, are left completely undocumented in both the schema and the description, so parameter coverage is only partially compensated.

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 'Create, update, or delete records,' a specific verb-resource statement, and then specifies exact HTTP semantics. This clearly differentiates write_record from read-oriented siblings like query_records.

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 write-tool context and notes that writes persist, which helps an agent decide to use it. However, it never names sibling tools or states when to prefer query_records or add_resource instead, so usage guidance is implied rather than explicit.

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