Verified, reproduced behavior of public HTTP APIs: spec gaps, errors, pagination, auth.
Scored across 9 tools
Most tools are distinct, but the retrieval tools overlap heavily: get_tool_knowledge already flags spec divergences that get_divergences surfaces, and get_tool_docs vs get_tool_knowledge return the same verified-claim data as Markdown vs structured records. Descriptions clarify format differences, but an agent could still misselect among the four knowledge-retrieval tools.
All nine tools follow a clean snake_case verb_noun pattern (get_divergences, list_tools, request_target, search_claims, get_request_status, etc.). No mixed conventions, abbreviations, or vague verbs.
Nine tools is well-scoped for an API-verification compendium, covering discovery, probing lifecycle, retrieval, search, and version comparison without bloat.
The lifecycle is largely covered: request a target, poll status, list coverage/versions, retrieve docs/claims/divergences, search, and diff versions. Minor gaps exist (no cancellation or re-probe of a request, limited filtering on list_tools), but nothing that blocks core workflows.
Where the live API contradicts its own OpenAPI spec: documented limits not enforced, types not validated, required parameters not required, enums accepting other values. Compact evidence; verbose=true adds response previews.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | tool name (e.g. github-rest), or the host / URL you are about to call (e.g. api.github.com) | |
| verbose | No | ||
| version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely new behavioral context: default output is 'compact evidence' and verbose=true adds response previews, which tells the agent how output size/verbosity behaves — something the annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core purpose followed by a colon-list of concrete divergence types, then the verbosity note. Dense but every clause carries information; 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?
With no output schema, the description does well to sketch the return shape ('compact evidence', previews under verbose), which is the key missing piece. However, it leaves the 'version' parameter completely undocumented and gives no scoping or error behavior, so the picture is only partially complete for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'tool' is documented, with an example). The description compensates for 'verbose' by explaining that it adds response previews, but the 'version' parameter is left entirely unexplained in both schema and description, so the compensation is partial.
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 (divergences between the live API and its OpenAPI spec) and enumerates the concrete categories of divergence — unenforced limits, unvalidated types, unrequired required params, loose enums. That is far more specific than the name alone and clearly distinguishes it from sibling tools like get_version_diff or get_request_status, though it never explicitly contrasts itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the content: you'd call this when auditing whether documented behavior matches reality. There is no explicit when-to-use/when-not-to-use guidance and no mention of how this differs from siblings such as get_version_diff, so the agent must infer the selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Status of a target request (pending, running, done or failed), with the run id and summary once processed.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description goes beyond them usefully by revealing the four possible status values and that the run id and summary only appear once processing completes, which tells the agent how to interpret an incomplete-looking response.
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?
One sentence, front-loaded with the resource and outcome; the parenthetical status list earns its place. Slightly dense phrasing ('with the run id and summary once processed') but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so reasonably by listing statuses plus run id and summary. It is thin only on the request_id input and on what an agent should do while status is pending, which are minor for a simple, fully-annotated read 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 0% for the single request_id parameter, so the description is the only place semantics could be supplied — yet it never explains what request_id is, where it comes from, or its expected form. 'A target request' is the only hint and it is too vague to compensate.
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 (a target request) and the exact information returned (status, run id, summary), and it enumerates the four status values. It doesn't explicitly contrast with request_target, but the 'target request' scoping makes the intent clear against siblings like get_divergences or list_tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: reading 'once processed' suggests polling a request previously submitted via request_target, but the description never states when to call it or what the alternative is if no request exists. No explicit when/when-not guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The verified behavior sheet for an API: Markdown built only from verified claims, with spec contradictions first, then sibling differences, undocumented rules, and per-endpoint behavior (error shapes, pagination, validation, auth), every line citing trial ids. Accepts a tool name, a host, or the full URL about to be called; a URL or path scopes the sheet to that endpoint plus a one-line index of the others. Brief by default (what would change the request); full=true adds per-parameter validation, response shapes and all evidence ids.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | the whole sheet: per-parameter validation, response shapes, all evidence ids | |
| path | No | request path to scope to one endpoint, e.g. /repos/github/rest-api-description/issues; template segments match anything | |
| tool | Yes | tool name (e.g. github-rest), or the host / URL you are about to call (e.g. api.github.com) | |
| brief | No | deprecated: the default; brief=false is the same as full=true | |
| version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral context: output is built only from verified claims with per-line trial-id citations, contradictions are surfaced first, and the brief-vs-full default controls output volume. It does not mention auth requirements or any rate limits, which keeps it short of a 5.
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 dense sentences, front-loaded with what the artifact is before moving to invocation and modes. Every clause carries information, though the middle enumeration of content sections is long enough that a reader must work to parse it in one pass.
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 burden of describing the return value, and it does so well by naming the sheet's sections and the brief/full distinction. The remaining gap is the undocumented 'version' parameter and the absence of routing guidance against sibling tools that surface similar claim/divergence data.
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 80%, so the baseline is 3, and the description goes beyond it by explaining what full=true actually adds (per-parameter validation, response shapes, all evidence ids) and by describing the scoping semantics of passing a URL versus a path versus a bare tool name. Only the 'version' parameter receives no explanation anywhere, which is the one gap.
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 artifact (a Markdown 'verified behavior sheet' for an API) and enumerates its contents: spec contradictions, sibling differences, undocumented rules, and per-endpoint behavior. That is far more concrete than a restatement of the name. It does not, however, explicitly differentiate itself from plausibly overlapping siblings like get_divergences or get_tool_knowledge, which it only references as content sections rather than as alternatives.
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 states the accepted inputs (tool name, host, or the full URL about to be called) and that a URL/path scopes the sheet, which implies a pre-request use case. But it never says when to prefer this over get_divergences, get_tool_knowledge, or search_claims, and there are no explicit exclusions. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every verified claim about an API as structured records (latest version by default): paginated, filterable by kind, spec divergences flagged, each with compact evidence (trial id, probe, status, request line). verbose=true adds response previews.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | required | type | auth | pagination | error_behavior | response_shape | undocumented_constraint | undocumented | other | |
| tool | Yes | tool name (e.g. github-rest), or the host / URL you are about to call (e.g. api.github.com) | |
| limit | No | default 100 | |
| offset | No | ||
| verbose | No | ||
| version | No | tool_version id; default latest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds real behavioral detail beyond them: pagination, kind filtering, flagging of spec divergences, and the evidence fields attached to each record. With no output schema, this return-shape disclosure is genuinely useful, though details like page size limits are absent.
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 dense sentence that front-loads what is returned before the modifiers, with no filler. The parenthetical and trailing clauses are packed but each carries a distinct fact (default version, evidence contents, verbose behavior).
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 appropriately describes the returned records and the verbose variant, and mentions pagination, which is what an agent needs to invoke and interpret it. Missing are practical bounds (limit/offset reintroduction beyond schema defaults) and any hint of how divergences relate to the get_divergences sibling.
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%, so the schema already documents kind, tool, limit, offset, and version. The description adds meaning only for verbose ('adds response previews'), which the schema leaves undescribed, and reinforces the latest-version default. That is incremental value, not full compensation for the uncovered gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: returning 'every verified claim about an API as structured records', which is concrete and distinguishable from a generic search. However it never names or contrasts itself with close siblings such as search_claims, get_divergences, or get_tool_docs, so the agent must infer boundaries from the returned fields.
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 notes defaults and filters ('latest version by default', 'filterable by kind') but gives no explicit when-to-use or when-not-to-use guidance against siblings like search_claims or get_divergences. An agent has no stated condition that selects this tool over those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What changed in verified behavior between two spec versions of an API (changed, added and removed claims), as opposed to what changed in the spec text.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | tool name (e.g. github-rest), or the host / URL you are about to call (e.g. api.github.com) | |
| to_version | Yes | ||
| from_version | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing what the result contains (behavioral claims diffed into changed/added/removed buckets) and by clarifying that it is not a textual spec diff, which sets expectations about output semantics.
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 core concept front-loaded. It is efficient, though the parenthetical category list and the 'as opposed to' clause make it slightly denser than necessary given nothing is said about inputs.
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 usefully sketches the return categories (changed/added/removed claims), which partly compensates. But for a 3-parameter tool with low schema coverage and a similarly named sibling (get_divergences), the definition leaves input semantics and sibling selection unexplained.
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 33%: only 'tool' is documented, while from_version and to_version are bare integers with no explanation. The description never mentions the parameters at all, so it does not compensate for the gap — it fails to say whether versions are numeric IDs, how to obtain them, or what happens with invalid/reversed ranges.
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 gives a specific verb and resource: it diffs verified behavior claims between two spec versions and enumerates the claim categories (changed, added, removed). It also distinguishes itself from a raw spec-text diff, which is a useful contrast, though it never names a sibling like get_divergences or list_versions.
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 phrase 'between two spec versions,' so an agent can infer this is the second-step tool after learning version identifiers. However, there is no explicit when-to-use statement, no prerequisites (e.g. do the versions need to exist / be discovered via list_versions first), and no routing to alternatives such as get_divergences or search_claims.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The APIs the compendium covers: each with the hosts its trials hit, trust tier, version count, and counts of verified claims and spec divergences.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the lower bar applies. The description adds genuinely useful disclosure beyond them: it specifies what each returned entry contains (hosts hit by trials, trust tier, version count, verified-claim and divergence counts), which is real information given there is no output 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?
A single compact sentence, front-loaded with the resource and then the payload fields. It is slightly elliptical as a fragment, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema, and annotations covering safety, the description carries most of the descriptive burden and does so by enumerating the fields each entry returns. It stops short of stating the identity key of each entry (name/URL) or ordering and pagination, which would fully close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies per the rubric. There is nothing for the description to clarify on the input side, and it correctly does not invent any.
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 the resource ('the APIs the compendium covers') and even enumerates the per-item fields, so an agent can infer this is the tool/API index. However, it is a noun fragment with no verb and no contrast against siblings like list_versions, get_tool_docs, or get_tool_knowledge, so the agent must infer that this is the top-level catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this versus the eight sibling tools, nor any note that it is the recommended entry point before drilling into get_tool_docs or list_versions. The agent is left to guess its place in the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The spec versions recorded for one API, newest first, each fingerprinted by its spec hash. The ids identify versions for get_version_diff.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | tool name (e.g. github-rest), or the host / URL you are about to call (e.g. api.github.com) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that: result ordering (newest first) and the identity of each entry (fingerprint hash + id usable downstream). No pagination or size limits are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the most useful facts (what is listed, ordering, entry identity) come first, with the downstream linkage last.
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 correctly carries the burden of describing the return shape: version entries with ids and spec hashes, ordered newest first. It omits any statement about result volume or truncation, which is the only meaningful gap for a small listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single required 'tool' parameter whose description already gives examples (tool name, host, or URL). The description adds only the scoping notion of 'one API', which the schema's parameter description already conveys in substance; 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 ('spec versions recorded for one API') and adds distinguishing behavior ('newest first, each fingerprinted by its spec hash'). It also explicitly connects to the sibling get_version_diff, so an agent can separate it from list_tools, get_divergences, etc. without opening 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 second sentence tells the agent what to do with the result ('The ids identify versions for get_version_diff'), which is clear usage context linking to a sibling. It stops short of explicit when-not-to-use guidance (e.g. when to prefer get_divergences instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queues a public, read-only, credential-free API for probing, from a target object { name, spec_url (OpenAPI 3 document), category?, include_paths?, baseline? (valid values for required params per path), optional_values?, server? }. The spec is fetched and parsed and the battery planned immediately; probing runs rules-only on the worker's next pass. Requires a per-user key; quota 3 requests per key per day. Returns a request id for get_request_status.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | the target definition; see targets/*.json in the repo for examples |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only covering the mutation/idempotency profile, the description carries the real behavioral load: auth requirement (per-user key), hard rate limit (3 requests per key per day), and the async execution model split between immediate spec fetch/parse and worker-pass probing. It also discloses the return value (a request id for get_request_status), which no output schema provides.
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?
Front-loaded with the core action and scope, then the argument shape, then operational constraints and the return value — an efficient ordering with no filler. It is a dense single paragraph with nested parentheticals, which slightly taxes scanning but every clause carries 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 one-argument, no-output-schema queueing tool this is complete: it explains the input object's shape, the auth and quota envelope, the async lifecycle, and what to call next for the result. Nothing an agent needs in order to invoke 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?
The schema for the single `target` parameter is a freeform object pointing at repo examples, so the description is the only real specification: it enumerates name, spec_url (OpenAPI 3 document), category, include_paths, baseline (with the meaning 'valid values for required params per path'), optional_values, and server. This adds substantial semantics the schema does not carry.
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 (queues a public, read-only, credential-free API for probing) and names the sibling it hands off to (get_request_status). An agent can distinguish it from get_divergences, search_claims, and the version tools without opening any 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 makes the context of use clear: request a probe target here, then poll with get_request_status, and the target must be a public, credential-free API (an implicit constraint that excludes private/authenticated ones). It stops short of explicitly naming when NOT to use it or naming an alternative request path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search over verified claims by host and symptom, e.g. "github per_page 500", "npm search size 0", "is latitude required on /v1/forecast": the lookup for an unexpected 4xx/5xx, a parameter that seems ignored, an odd page, or wrong filter results. Optionally restricted to one API (name, host or URL). Compact evidence unless verbose=true.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | tool name (e.g. github-rest), or the host / URL you are about to call (e.g. api.github.com) | |
| limit | No | ||
| query | Yes | ||
| verbose | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds value beyond that by disclosing output behavior ('Compact evidence unless verbose=true') and the optional scoping to a single API, which the annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the core purpose, then examples, then use cases, then the optional scoping and verbosity note. A single dense paragraph with no wasted sentences, though the inline example queries make it slightly heavy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with rich annotations and no output schema, the description supplies purpose, triggers, scoping, and result-format expectations, which is close to sufficient. The only meaningful gap is the undocumented 'limit' parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at only 25%, the description has to carry parameter meaning, and it does for two of four: it explains 'tool' as an API name, host, or URL, and clarifies that 'verbose' toggles compact vs. full evidence. However, 'limit' is never addressed in either the schema or the description, so the compensation is incomplete.
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+resource: 'Full-text search over verified claims by host and symptom', and the concrete query examples make the scope unmistakable. It doesn't name a sibling tool outright, but the debugging framing (failed request, ignored parameter) implicitly separates it from get_tool_docs and get_request_status.
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 states concrete triggering situations — an unexpected 4xx/5xx, a parameter that seems ignored, an odd page, or wrong filter results — which is clear context for invocation. It stops short of explicit exclusions or naming the alternative sibling tools to use instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_tool_docs2 fields changedInput schema / properties / brief / descriptionPrevious value: -"divergences, undocumented rules, auth, pagination and error behavior only"New value: +"deprecated: the default; brief=false is the same as full=true"Input schema / properties / fullAdded value: +{
+ "description": "the whole sheet: per-parameter validation, response shapes, all evidence ids",
+ "type": "boolean"
+}get_divergencesget_request_statusget_tool_docsget_tool_knowledgeget_version_difflist_toolslist_versionsrequest_targetsearch_claimsValidated API and app vulnerability findings with remediation guidance.
Six Product API tools require authentication; protocol metadata discovery is keyless.
Verified AI-agent outcomes: secret scanning, JSON cleanup, dedupe, anomaly and schema checks.
Find, document and execute authenticated API calls across 700+ apps via one MCP server
Add one secure layer between your agents and this server.
