Mockbird

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

With no annotations, the description must carry the full burden of behavioral disclosure. It does state that the tool creates a resource and seeds it with fake data, and it clarifies seed count semantics (default, max, empty). However, it does not address side effects like overwriting behavior, idempotency, required permissions beyond adminKey, or failure modes, leaving some behavioral aspects opaque.

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

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

The description is front-loaded with the main purpose, then logically breaks down the two modes (template vs fields) and seed behavior. It is dense and lengthy, especially the field-type enumeration, but that list is directly actionable for an agent deciding whether to use custom fields, so the detail 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 tool with 6 parameters, no annotations, and no output schema, the description covers the key aspects: what the tool does, the two input modes, supported data types, and seed limits. It could be more complete by explaining return values or duplicate-resource behavior, but it is largely sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds substantial value beyond the schema by enumerating valid template examples, listing the full set of accepted field types, explaining the oneOf enum construct, and detailing seed constraints. This goes well beyond the schema's brief 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 opens with a specific verb ('Add') and resource ('resource/collection'), clearly distinguishing this from sibling tools like import_data or write_record. It further clarifies that the tool seeds the resource with fake data, making its scope 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 clear within-tool guidance on choosing between template and fields, and specifies seed behavior. However, it does not explicitly contrast this tool with siblings such as import_data or write_record, nor does it state when not to use it. Usage is implied by the name and primary action rather than stated as explicit selection criteria.

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

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

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 carries the full behavioral disclosure burden. It is transparent about the one-time display of adminKey, the live baseUrl behavior, standard REST CRUD capabilities, CORS enabled, no auth needed, and the streaming/embedding behavior of the openai preset.

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 every clause earns its place: return fields, adminKey warning, preset definitions, starter vs blank behavior, and live endpoint characteristics. It front-loads the most critical information about the returned values and the one-time credential.

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 and no annotations, this description is operationally complete. It specifies what is created, what is returned, how to choose a preset, what the resulting API supports, and what must be saved for later admin operations. There is no critical gap for an agent deciding whether and how to call it.

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

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

While the schema already covers both parameters at 100%, the description adds substantial meaning: it explains exactly what each preset seeds, contrasts omitting the preset with using 'blank', and clarifies that name is optional. This goes well beyond the enum labels and schema descriptions.

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

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

The description opens with a specific action and resource: 'Create a new mock REST API project.' It also names the return contract ({id, adminKey, baseUrl, resources[]}) and explains the main variants (preset, starter, blank), making it easy to distinguish from sibling operations like add_resource or project_info.

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

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

It gives explicit guidance on when to omit the preset versus use 'blank', and names add_resource and import_data as the follow-up tools for building out a project. It also flags that the adminKey is required for admin operations such as add_resource, custom_route, and snapshots, helping the agent plan subsequent calls.

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?

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?

With no annotations, the description carries the full burden and does so well. It discloses auto-detection behavior, per-format transformation rules, a size constraint, and the exact return shape including id, adminKey, baseUrl, and warnings.

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 highly efficient. Every sentence conveys meaningful behavior: format mapping, size limit, and return structure. The primary action is front-loaded and the format list is easy to scan.

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 and lack of an output schema, the description is complete enough for an agent to call it correctly. It covers what inputs are accepted, how each is handled, the size limit, and what the response will contain.

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 all parameters. The description adds useful context about content auto-detection and seeded data, but it does not materially expand on parameter semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Create a live mock API from existing artifacts.' It enumerates distinct artifact types and their mappings, making it easy to distinguish from siblings like add_resource or create_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 clearly implies when to use this tool: when the user has an existing OpenAPI spec, db.json, Postman Collection, or CSV/TSV to convert into a mock API. It also provides a 512 KB limit, which is a useful exclusion criterion, though it does not explicitly name alternatives.

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

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

With no annotations present, the description carries the full burden of behavioral disclosure, and it delivers: it discloses that authorization is redacted to its scheme, that only a body snippet is shown for writes, that adminKey is required except for the public 'demo' project, and that the data is the most recent requests. This is strong transparency for a read-only inspector. It could have added details about empty-result behavior or lack of side effects, but the 'Read' framing implies non-mutating.

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 composed of four purposeful sentences: the core definition, the verify workflow, the pairing with custom_route, and the adminKey note. It is densely informative without being padded, and the most important purpose is front-loaded. It earns a 4 rather than a 5 because the density is high and the flow could be slightly tighter, but every sentence contributes.

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

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

Given no output schema, the description compensates by enumerating the returned fields (method, path, query, status, origin, captured headers, body snippet). It also covers auth requirements, a usage workflow, and a companion tool for a key use case. Minor gaps remain: no mention of empty result behavior, ordering, or the default/max limit (though limit is in the schema). Overall, it is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaningfully beyond the schema: the adminKey exemption for 'demo' is already stated in the schema ('not needed for demo'), and project and limit are self-explanatory in both places. The description's extra details about captured fields relate to return data, not to parameter semantics. Therefore it meets the baseline but does not exceed it.

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

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

The description opens with a specific verb and resource: 'Read the project's request inspector' and enumerates exactly what is returned (method, path, query, status, origin, headers, body snippet). It positions the tool distinctly from its siblings by framing it as the mock-API request log viewer, which no other sibling name suggests. Clear, specific, and differentiates from surrounding 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 states when to use it: 'Use it to VERIFY what your app / tests / webhook sender actually sent' and provides a mini-workflow: point code at the mock, run, inspect. It also notes a companion tool, custom_route, for webhook payload and signature debugging. However, it does not explicitly name alternatives to avoid (e.g., query_records for stored data), so it stops short of a full when-not-to-use statement.

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

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

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?

With no annotations provided, the description carries the full burden of explaining behavior. It discloses that snapshots save the entire dataset, restore exactly later, and can serve read-only requests without touching live data. However, it does not explicitly warn that restore overwrites current live data or that delete is permanent, nor does it mention any adminKey-level authorization requirements beyond the parameter name.

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 focused sentences that front-load the purpose and then add the most important behavioral nuance (read-only snapshot serving). Every clause adds value and there is no redundancy or 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 there is no output schema and no annotations, the description explains the core workflow well but omits return values, error conditions, and explicit semantics of restore/delete on live data. It also references a cross-tool integration with query_records that adds useful context, but for a tool with four actions and auth requirements, an agent would still need to infer some operational details.

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 25%, so the description must compensate for the four parameters. It explains the semantic meaning of 'name' and covers all four action values (save, restore, list, delete) in prose, and it describes the mock_snapshot query parameter. Yet it does not clarify the 'project' or 'adminKey' parameters, leaving part of the input surface under-documented.

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 specific verbs for each operation (save, restore, list, delete) on a clear resource: the project's entire dataset. It distinguishes itself from sibling tools by explaining the snapshot lifecycle and the mock_snapshot read-only serving mechanism. An agent can immediately understand what this tool does without opening the schema.

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

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

The description clearly frames this as a tool for deterministic test fixtures and parallel test scenarios, which tells the agent when it is appropriate to use. It also points to a specific integration with query_records via the mock_snapshot parameter. However, it does not explicitly name alternative tools or state when not to use snapshots, so it stops short of a 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, the description carries the full behavioral disclosure burden and meets it comprehensively: 30-minute polling, 8s timeout, 2xx/3xx up criteria, debounced alerts, one down/one up message, webhook format variations, HMAC signature details, limits, and 30-day removal for unpolled monitors. It also warns that id/secret cannot be recovered. No contradictions.

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

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

The text is dense but well organized: a one-line value proposition, then action-by-action behavior, then limits and alternative routing. Each clause carries unique information — webhook formats, debounce behavior, badge/feed/status page, retention policy — without filler. Every sentence earns its place for a multi-action tool.

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

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

There is no output schema, so the description needs to convey return semantics, and it does: create returns current state, status page, badge.svg, Atom feed, and id/secret; poll returns transitions and latest check; info and delete cover their own results. Limits, retention, and alternative tool usage are also covered, making the tool fully invocable by an agent.

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

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

Although the schema has 100% coverage, the description adds operational meaning beyond parameter names: id and secret jointly manage the monitor and are irrecoverable, notify behaves differently per endpoint type, poll returns transitions since last poll with empty events meaning no change, and delete immediately frees a slot. This far exceeds the schema's basic descriptions.

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

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

The opening line 'Free downtime alerts for any public URL' states the tool's core purpose with a specific verb and resource. It then enumerates four concrete actions (create, poll, info, delete) and explicitly names heartbeat as the inverse tool, so an agent can clearly distinguish it from siblings.

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

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

The description gives explicit routing guidance: webhook-based alerts vs pollable monitors depending on whether notify is supplied, and directs cron/scheduled users to the heartbeat sibling. It does not mention other monitoring siblings like check_api_status or watch_service_status, so it is not a perfect 5, but it provides strong contextual usage rules.

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.