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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value beyond them: it enumerates the possible status values and prescribes the polling loop on 'scraping', which is exactly what an agent needs to drive the call correctly.

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 short sentences, front-loaded with the purpose, then the return values, then the polling instruction. Nothing 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 output schema, the description correctly carries the return-value burden by listing the status strings. The only gap is what the 'results' payload contains on completion, but the polling contract an agent needs is fully specified.

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

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

Schema coverage is 100% and the schema already documents the single id parameter as 'returned by supadata_crawl'. The description only reinforces this via 'the same id', adding polling-reuse semantics but little else beyond the schema baseline.

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 ('Check crawl job status and retrieve results'), which distinguishes it from the sibling status-check tools (extract, transcript) by resource. It stops short of explicitly naming those siblings, but the scope is unambiguous.

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

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

Gives a clear conditional usage rule: if status is 'scraping', re-call after a few seconds with the same id. This tells the agent how to poll. It does not state when to prefer this over the other check_*_status siblings, but the context is otherwise clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavior: the four possible status values and the retry cadence, which is the core operational detail for a polling tool. It stops short of saying what a completed job's results contain.

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 short sentences, front-loaded with the purpose, then the return values, then the polling instruction. Every sentence carries distinct information with no padding.

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 enumerates the status values and tells the agent how to loop. The remaining gap is what 'results' actually look like on completion, but the polling contract an agent needs is largely present.

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% and the single parameter's description already states it is the job id returned by supadata_extract. The description only echoes this via 'with the same id', adding no format, uniqueness, or expiry details beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Check extract job status') and adds 'retrieve results', which is the actual payoff. The resource noun 'extract job' cleanly separates it from the sibling polling tools supadata_check_crawl_status and supadata_check_transcript_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?

Gives an explicit polling rule: if status is not 'completed' or 'failed', call again after a few seconds with the same id. That is concrete when-to-use guidance, though it never states the precondition that the id must come from a prior supadata_extract call or names 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds the terminal vs. non-terminal status contract and the repeat-polling expectation, which is exactly the behavior an agent needs. It doesn't say what 'retrieve results' actually returns on completion or whether 'failed' carries error detail.

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 short sentences: purpose first, then the return contract, then the polling instruction. Every sentence earns its place with no filler.

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

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

No output schema exists, so the description carries the return-value burden, and it does so by enumerating the four statuses and telling the agent when to stop polling. What's missing is a brief note on what a completed result contains or whether a failed status includes diagnostic 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?

Only one parameter, and the schema already documents it at 100% coverage. The description reinforces its semantics by specifying that the same id must be reused across polls, which adds operational meaning beyond the schema's 'job id returned by supadata_transcript'.

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 ('Check transcript job status and retrieve results') and enumerates the possible outcomes, which is more than a restatement of the title. It implicitly distinguishes itself from the crawl/extract status siblings by naming the transcript job resource, though it 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?

Gives concrete, actionable polling guidance: if status is not 'completed' or 'failed', call again after a few seconds with the same id. It doesn't explicitly state the prerequisite (that the id comes from starting a transcript job) in the description body, but the conditional loop is clear and correct.

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 cover safety (readOnly, openWorld, idempotent=false, destructive=false), and the description goes beyond them with plan gating, the upgrade-required failure semantics, and the asynchronous jobId-then-poll workflow. This is meaningful behavioral context the annotations do not provide.

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: purpose, plan/error handling, and return-value workflow. Front-loaded with the action and the polling instruction is placed where it is needed.

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 correctly discloses the return (jobId) and the exact sibling to poll it with, and covers the plan-gating edge case. Nothing essential for a correct invocation 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% and already documents url and limit richly (including 1-5000 range, default 100, 1 credit per page), so the schema carries the parameter burden. The description adds no parameter syntax or format detail beyond what the schema states.

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?

Specific verb+resource: 'Create a crawl job to extract content from all pages on a website.' Clearly distinguishable from siblings like supadata_scrape (single page) and supadata_map, and it names the exact follow-up tool.

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

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

States the plan restriction and what to do on an upgrade-required response ('tell the user rather than retrying'), plus routes the agent to supadata_check_crawl_status for polling. No explicit when-not-to-use versus scrape/extract, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds the crucial non-obvious behavior: extraction is asynchronous and returns a jobId that must be polled elsewhere. It omits rate limits, credit cost, or failure modes, which keeps it below 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?

Three tight sentences: capability first, input requirements second, async follow-up last. Nothing is padded and the downstream call is placed where an agent needs it.

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 discloses that the immediate return is a jobId rather than extracted data, closing the biggest gap for this tool. It leaves residual unknowns such as media size/duration limits or processing latency, but the async contract is complete.

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

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

Schema description coverage is 100%, so all three parameters (url, prompt, schema) are already documented in the schema. The description restates the prompt/schema-or-both rule without adding format, syntax, or size guidance, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ("Extract structured data from a video URL using AI") and names the companion tool supadata_check_extract_status, which separates it from siblings like supadata_transcript or supadata_scrape. An agent can identify the tool's job 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?

Explicitly states that the caller must supply a prompt, a JSON Schema, or both, and that the returned jobId should be polled with supadata_check_extract_status. It does not contrast this tool against alternatives like supadata_transcript for plain text or supadata_metadata, so routing among siblings is only partly covered.

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 declare readOnly, idempotent, non-destructive, and open-world behavior, so the bar is lower. The description adds genuinely new context: that it lists URLs without fetching content and that each call costs 1 credit, which matters for budgeting. It does not mention result limits or pagination behavior for large sites.

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

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

Two tight sentences with no waste. The core behavior leads, followed by the routing guidance, and the credit cost is a brief trailing note.

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, read-only discovery tool with no output schema, the description covers what it does, when to use it, and its cost. It could say more about the shape or volume of the returned URL list, but nothing essential to correct invocation 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% and the single url parameter is fully documented in the schema including the https:// requirement, so parameter meaning is already handled. The description adds nothing further about the parameter; baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (URLs found on a website) plus the key scoping constraint that content is not fetched. This cleanly separates it from supadata_scrape (which reads content) and supadata_crawl (which traverses), both named in the description.

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

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

Explicitly names two use cases and the alternatives that follow: discover pages before choosing which to read with supadata_scrape, or check site size before starting a supadata_crawl. The agent has a clear decision rule for selecting this tool over its siblings.

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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds value by enumerating the returned fields unambiguously (platform info, title, description, author, engagement stats, tags, creation date), but doesn't mention failure modes for unsupported platforms/private content or rate limits.

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

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

Three sentences, zero waste: scoping clause, return-value clause, sibling-routing clause. Front-loaded with the core action and platform list.

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 read tool with full annotation coverage, no output schema, and no nested objects, the description covers purpose, scope, return contract, and alternative routing. Nothing an agent needs 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?

Schema description coverage is 100% and only one parameter exists, so the schema already documents the URL. The description confirms platform support but adds no syntax or format guidance beyond what the schema property description provides. Baseline 3 is appropriate.

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

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

States a specific verb (Fetch) and resource (metadata from a media URL), enumerates supported platforms, and names the sibling it is not (supadata_transcript) with a crisp distinction between details vs. spoken content. An agent can route between them without opening either 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?

Explicitly says when to use this tool ('details about a video or post') versus the alternative ('use supadata_transcript for what is said in it'). The only missing piece is explicit single-URL scoping, which is implied by 'a media URL'.

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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the credit cost (1 credit) and the shape of the returned content (Markdown, title, description, links). No notable gap remains, though return format details are still fairly high-level.

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 tightly packed sentences: what it returns, when to use it, and the sibling alternatives plus cost. Front-loaded with the primary capability and zero 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 Markdown content, title, description and links. Combined with the fully documented input schema and the safety annotations, 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the noLinks-to-links relationship and the lang ISO code. The description only restates that links are returned and does not add syntax or edge-case detail beyond the schema, 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?

Specific verb (Fetch) and resource (single web page) with an explicit statement of what is returned (main content as Markdown, title, description, links). It clearly distinguishes itself from supadata_map and supadata_crawl by naming both 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?

Explicitly states the use case ('read or summarize a specific URL') and routes the agent to alternatives with their selecting conditions: supadata_map for discovering pages, supadata_crawl for bulk fetching. Nothing is left to inference.

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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: the dual return mode (transcript directly vs. jobId for large files) and the polling follow-up. It stops short of mentioning auth requirements, rate limits, or failure modes, so it is not maximally 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 sentences, zero filler, front-loaded with the core capability before the exclusion and the async caveat. Every sentence carries information an agent needs to select and call the tool correctly.

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 compensates by explaining the two possible return shapes (transcript or jobId) and the follow-up tool needed for the latter. Combined with the platform coverage, the exclusion rule, and complete schema param docs, nothing essential for correct invocation 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%, and the schema already documents lang (ISO 639-1 + fallback), mode (native/auto/generate semantics), text (plain text vs timestamped segments), and chunkSize (minimum 50, ignored when text is true). The description adds no parameter-level meaning beyond that, 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+resource ('Get the transcript ... of a video or post') and enumerates the supported platforms (YouTube, TikTok, Instagram, X, Facebook, plus direct audio/video file URLs). It also explicitly separates itself from supadata_scrape by naming the excluded resource type, so an agent can distinguish it from siblings 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?

Gives an explicit when-not ('Not for ordinary web pages: use supadata_scrape for those') with the alternative named. It also routes the async case: large files return a jobId and the agent should use supadata_check_transcript_status to poll, which is a clear conditional workflow rather than implied usage.

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