MINIMALCULT

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

Annotations cover the read-only and open-world profile, so the bar is lower, and the description still adds real context: it discloses that the response is a signed check and enumerates the possible status values (witnessed, changed_recently, hash_mismatch, not_witnessed, sanctions_listed, not_listed). It does not mention auth requirements, rate limits, or what 'anchored record' freshness means.

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

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

Two sentences, front-loaded with the operation and supported target types, then the return shape. The status enum parenthetical is long but earns its place because there is no output schema; nothing is 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?

With no output schema, the description carries the return-value burden and does so by naming the statuses and the fact/diff payload. For a 6-parameter read-only verification tool this is nearly complete; only auth/access expectations and the relationship to the record_* tools are 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 67%, and the description compensates by mapping the target categories to the type enum and explaining the intent of the hash parameters ('the hash you are about to install'), which the schema alone frames only as sha256/integrity. It adds nothing for as_of or version, which the schema already documents.

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 ('Check') and enumerates the exact resource types (MCP server, npm/PyPI package, MCP endpoint URL, TON address) plus the reference point ('against the anchored record'). An agent immediately knows this is a verification tool rather than a lookup, though it never names its record_* siblings to draw the line explicitly.

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 parenthetical 'optionally with the hash you are about to install' implies the pre-install verification use case, and 'Check before you trust' frames intent. But there is no explicit when-to-use/when-not, no statement of how this differs from record_get or record_search, and no prerequisite 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?

Annotations already flag this as a non-read-only, open-world, non-destructive call; the description goes further by disclosing the return contract (monitor id plus a secret shown only once), the signing scheme (HMAC-SHA256 in header MINIMALCULT-Signature), and a quota (3 monitors per address free). That is real context an agent cannot get from the annotations.

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

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

Three tight sentences: what it does, what it returns, then the quota. The action and event scope are front-loaded and no sentence is 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 two-parameter subscription tool with no output schema, the description covers the action, trigger events, return values, signing, and quota. Minor gaps remain around verification setup and how to later remove a monitor, but nothing essential to making the call 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 both parameters already document their formats (public https URL, rec_/mcp:/npm:/pypi: identifiers). The description adds only indirect meaning via "webhook" and the free-tier limit; it does not explain payload delivery or retry behavior, so the baseline 3 applies.

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

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

States a specific verb and resource ("Subscribe a webhook to changes of a record") and enumerates the triggering events (new version, tool description changed, removed). No sibling tool (check, record_get, record_search, record_versions) creates subscriptions, so an agent can select this unambiguously.

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?

Usage is implied by the event list and the required url/record pair, but there is no explicit statement of when to prefer this over polling with record_versions or check. No exclusions or prerequisites (e.g. auth requirements) are given.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuine value by saying the response includes the record's 'latest recorded fact', giving a hint of return shape. It does not say whether a missing id errors or returns empty, nor whether lookup is exact-match only.

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

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

A single compact sentence with the key information front-loaded and no filler. The tradeoff is that it is a noun phrase rather than a sentence, which slightly reduces scannability.

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-parameter read tool with no output schema, the definition covers the resource, the accepted identifier namespaces, and what the response contains. Remaining unknowns (error behavior, exactness of matching) are minor for a simple lookup.

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

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

With one parameter and 0% schema description coverage, the description carries the burden and does so reasonably: it enumerates the accepted id forms (rec_ ids and the mcp:/npm:/pypi: source-id patterns) that the bare 'string' type does not express. It stops short of examples or format validation rules.

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 the resource (one record) and the retrieval key forms (rec_ id, or source ids like mcp:<registry>, npm:<name>, pypi:<name>), which separates it from record_search (query-based) and record_versions (history). It lacks an explicit verb ('Get' only appears in the title) and never names the siblings, so it falls short of a 5.

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

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

Usage is only implied: the id-keyed phrasing implies 'use this when you already have an exact identifier, otherwise search.' There is no explicit statement of when to prefer record_search or record_versions, and no note about what happens on a miss.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds useful context about returned fields (rec_ ids, on-record-since dates, latest versions), but says nothing about ranking, empty-result behavior, or the limit default of this potentially multi-result search.

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

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

A single front-loaded sentence with the searchable domains first and the return shape last; nothing is padded. It is dense but every clause carries information an agent needs.

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

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

With no output schema, the description's mention of return fields is genuinely valuable. However, for a 3-parameter search with zero schema description coverage and unclear relationship to record_get/record_versions, the definition leaves too much for the agent to infer.

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 0%, so the description must carry parameter meaning. It clarifies only 'query' as matching name or words, while the type enum (mcp_server / npm_package / pypi_package) and the limit cap of 50 are left entirely to the bare schema.

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

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

States a specific verb (find) and resource (records), and scopes the domain to MCP servers and npm/PyPI packages. It implicitly contrasts with record_get/record_versions by being a name/keyword lookup, but never names those siblings explicitly.

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?

Usage is only implied: an agent can infer this is the discovery step before record_get. There is no explicit statement of when to prefer it over check, record_get, or record_versions, and no guidance on when to use the type filter instead of free-text query.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely new behavioral context beyond it: results are ordered newest first, and each entry carries proof and diff links, with the kinds of facts enumerated. It stops short of describing pagination behavior or what an empty result looks like, but it is meaningfully richer than the annotations.

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

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

A single front-loaded sentence that leads with what is returned, then enumerates fact types, ordering, and included links — no filler and nothing buried.

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 two-parameter read tool with no output schema, the description usefully characterizes the returned items and their ordering, which is the main thing it must do. However, with zero schema coverage it should also explain the id's expected form and what limit does, and it omits both.

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 0%, so the description carries the full burden, and it only weakly implies that 'id' identifies the target record. The 'limit' parameter (1-100, presumably page size with an unknown default) is never mentioned, leaving half the parameters unexplained in both places.

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 resource — the recorded facts (versions, registry entries, package artifacts, tool descriptions) of a record — and scopes it as reading the history of one identifiable record. That implicitly distinguishes it from record_search (querying across records) and record_get (current state), though it never names those siblings or uses an explicit verb like 'list'.

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

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

There is no when-to-use guidance at all: nothing tells the agent to reach for this instead of record_get when it needs history, or instead of record_search when it has no id. The reader must infer both the trigger condition and the alternatives from the phrase 'of a record' alone.

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