CivicDataForge Public-Records Data

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

The description adds behavior beyond the annotations: it clarifies that terminal runs are unaffected, which reinforces the idempotentHint and qualifies the destructiveHint. It also discloses the ownership requirement. No contradiction with annotations exists.

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, tightly worded sentence conveys the core action, scope, and an important edge case. There is no filler or redundant restating of the tool name or schema.

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

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

The description is complete enough for a simple destructive action with annotations and a fully documented schema. It explains the main operation and the terminal-run behavior, though it doesn't mention what happens if the runId doesn't exist or whether the abort is reversible; annotations cover safety context.

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 both runId and gracefully are already documented in the input schema. The description adds no extra parameter-level meaning, but it also doesn't need to because the schema fully covers the parameters.

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 action ('Abort'), a clear resource ('Actor run'), and important scoping conditions ('caller-owned', 'starting or running'). This clearly distinguishes it from sibling tools like get-actor-run, which only reads run state.

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 conditions: only for runs that are starting or running, and only caller-owned runs. It also implicitly says when not to use it by noting 'Terminal runs are unchanged', though it doesn't name an alternative tool or explicitly contrast with get-actor-run.

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

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

The description discloses the caller's APIFY_TOKEN usage, potential Apify usage consumption, 60-second wait ceiling, 1,000-row maximum, and the fact that government records are not modified. These operational side effects go well beyond the sparse annotations and give an agent a clear expectation of cost, latency, size, and non-mutation.

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 with no filler: the first front-loads the intended use case and domain scope, and the second packs the key operational constraints. Every clause contributes information an agent needs before invoking.

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?

Despite the operational constraints, the tool is complex (9 params, nested subject/evidence objects) and has no output schema. The description does not explain return shape, how to structure subject identifiers for each task, error/timeout behavior, or receipt/retention semantics, so an agent would still be guessing at invocation 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 0%, and the description does not compensate: it does not explain subject, evidence, retentionDays, transactionGate, previousReceiptHash, or screenRestrictedParties. It gestures at task categories, but an agent cannot derive the actual input semantics for most of the nine parameters from the 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 opens with a concrete routing verb and enumerates the supported evidence domains: U.S. property, India company/supplier, restricted-party, EPA facility, and China-facing intake. It distinguishes this gateway from the sibling data-source tools by framing the result as one minimized, receipt-bound packet and by noting it starts an Apify Actor.

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?

'Use for routing...' gives an explicit invocation context and lists supported intake categories. However, it never states when not to use the gateway or points to the specialized sibling tools (e.g., EPA, LEIE, property) as alternatives, so the routing decision between this aggregator and a direct data tool 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?

The description goes well beyond the annotations by disclosing concrete side effects: it starts an Apify Actor with the caller's APIFY_TOKEN, may consume usage, blocks for up to 60 seconds, and does not modify government records. This is highly valuable because the annotations only mark it as non-read-only and non-idempotent without explaining why.

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 deliver purpose, scope, side effects, latency, result limits, and a clear exclusion without filler. The purpose is front-loaded and operational caveats follow logically.

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

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

For a tool with no output schema, the description usefully describes what evidence comes back (identity, compliance, inspection, enforcement), why environmental safety stays UNKNOWN, and the operational envelope. It could be more complete by translating the nine optional parameters into a clear selection strategy, though the input schema's root-level guidance fills part of that 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?

With schema description coverage at only 44%, the tool description needed to compensate by explaining how the nine optional parameters relate to selecting a facility or bounding the query. It does not do so; it only repeats high-level notions of a bounded query and result limits. The schema has some root-level guidance, but the description itself adds little parameter-level meaning.

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

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

The description names a specific resource (EPA ECHO facility data) and a concrete action (bounded query), and enumerates what evidence it preserves: identity, compliance, inspection, and enforcement. It also explicitly excludes environmental safety conclusions, which makes its scope sharply distinguishable from sibling evidence 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 says 'Use for a bounded EPA ECHO facility query' and gives practical constraints: Apify usage may be consumed, waits up to 60 seconds, and returns at most 1,000 rows. However, it does not name sibling tools or state explicit when-not-to-use conditions, so it stops short of full alternative routing.

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 only convey open-world, read-only-false, idempotent-false, destructive-false. The description adds valuable behavior: starts an Apify Actor, 'may consume Apify usage', 'waits up to 60 seconds', 'returns at most 1,000 source-linked rows', and 'without modifying government records'. This is exactly the kind of operational context beyond structured 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?

Two sentences with no filler. The first sentence establishes purpose and alternatives; the second lists side effects and limits. Information density is high and front-loaded.

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?

Despite seven optional parameters and no output schema, the description covers purpose, scope, alternatives, side effects, timeout, output cap, and non-mutating character. This is sufficient for an agent to select and invoke the tool correctly; field-level detail is already in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful operational context not present in the schema, notably the global 'at most 1,000 source-linked rows' cap that constrains maxRecords, and the 60-second wait. This earns a 4.

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 the exact use case ('Florida statewide DBPR vacation-rental and lodging-license evidence') and names neighboring tools for adjacent scenarios. It clearly distinguishes itself from str-permit-regustry and property-violations, so an agent can select it 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?

Description explicitly tells when to use the tool ('Use for Florida statewide DBPR vacation-rental...') and when not to use it ('For municipal STR permits use str-permit-registry; for code violations use property-violations'). This is direct routing guidance to 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?

The description goes well beyond the annotations, disclosing that it starts an Apify Actor with the caller's APIFY_TOKEN, may consume Apify usage, waits up to 60 seconds, returns at most 1,000 source-linked rows, and does not change the source list. These side-effect, timeout, and scope details are valuable and are not present in the annotations or 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?

Three sentences with zero filler: purpose first, exclusion caveat second, and execution semantics third. Every sentence earns its place and the most important scoping information is front-loaded.

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 this tool's complexity—multiple modes, external APIs, API keys, and no output schema—the description holds back some context like the screen/filter mode distinction and optional CMS/SAM enrichment. The schema fills most gaps, but without an output schema a more explicit note on return record shape would have made it fully 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?

The input schema already provides rich, near-100% descriptions for every parameter including mode, screenList, samApiKey, and enrichment flags. The tool description adds only a high-level summary of searchable dimensions, which is useful but does not meaningfully increase understanding beyond what the schema already 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 action ('find review candidates') and resource (HHS-OIG LEIE), and lists concrete search dimensions: name, valid NPI, state, specialty, or exclusion type. It also explicitly distinguishes the tool from identity adjudication and facility licensing, which clearly separates it from sibling 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?

It tells the agent when to reach for this tool ('Use to find review candidates') and gives clear negative guidance ('Do not treat as identity adjudication or use for facility licensing'). It does not name an alternative tool for those excluded actions, so while the context is clear, the alternative path is left implicit.

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

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

The description discloses meaningful runtime behavior beyond the annotations: it starts a bound Apify Actor, uses the caller's APIFY_TOKEN, may consume Apify usage, waits up to 60 seconds, returns at most 1,000 rows, and does not modify government records. This is highly valuable and does not contradict 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?

The description is two sentences with no filler. It front-loads the tool's purpose and routing guidance, then states operational constraints. Every clause adds useful 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?

The description covers purpose, scope, alternatives, cost behavior, timeout, row limits, and non-destructiveness, which is strong for a complex tool. The only notable gap is that there is no output schema and the return shape is only vaguely described as 'source-linked rows,' but the rich parameter schema mitigates this.

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 each parameter already has detailed semantics such as county limitations, state availability, deficiency-count restrictions, and inspection-row caps. The description itself does not add parameter-level meaning, but the baseline of 3 is appropriate because the schema carries the full burden.

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 explicitly states the tool is for cross-state childcare licensing, inspection, and deficiency research, naming both the domain and the multi-state scope. It also differentiates itself from texas-childcare-licensing, so an agent can distinguish it from the closest sibling without reading 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?

It gives an explicit when-to-use condition (cross-state research) and an explicit when-not-to-use condition with a named alternative (Texas-only operations should use texas-childcare-licensing). This leaves little ambiguity for tool selection.

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

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

The description goes well beyond the annotations by disclosing that the tool starts an Apify Actor, consumes the caller's APIFY_TOKEN, may incur usage, waits up to 60 seconds, returns at most 1,000 rows, omits certain personal-data fields, and does not modify government records. This gives the agent a clear picture of external side effects and 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?

The description is dense and information-rich, with the primary use case front-loaded and operational constraints, legal context, and exclusions following. No sentence is wasted, though the second sentence is long and could be split for easier scanning.

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

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

The description covers usage scope, data-source provenance, licensing, privacy caveats, returned-row limits, field omissions, verdict exclusions, timeout behavior, cost implications, and non-modification of government records. It does not detail the exact output row structure, but the absence of an output schema is partially mitigated by the mention of 'source-linked rows' and omitted fields.

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 has 100% description coverage, so the baseline is 3. The description reinforces the importance of the nine-digit organisation number and bounded name search, but it does not add materially new parameter-level details beyond the schema's own thorough 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 use case—'exact nine-digit Norwegian organisation-number evidence or bounded company-name research'—and names the authoritative source, Brønnøysundregistrene. This clearly distinguishes the tool from sibling tools focused on other registries and from generic Apify control 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 the tool and defines its limits: it is for organisation-number evidence or bounded company-name research, and it 'never issues a KYC, procurement, sanctions, or eligibility verdict.' It does not explicitly name an alternative tool, but the boundary conditions are strong and practical.

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

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

The description discloses important side effects and operational constraints beyond what annotations provide: it starts an Apify Actor using APIFY_TOKEN, may consume Apify usage, waits up to 60 seconds, returns at most 1,000 rows, and does not modify government records. This complements the annotations without contradicting them.

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. The first sentence states the core purpose, the second gives exclusions, and the third covers operational behavior, timeout, limits, and side effects. Every sentence earns its place without redundant 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?

The description is complete enough for an agent to decide when to use the tool and to understand invocation consequences: authentication, usage cost, timeout, result cap, and non-modification of government records. Parameter details are already fully covered in the schema, so no important selection or invocation context 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%, with each parameter already described in the input schema: cities, status, and maxRecordsPerCity all have meaningful descriptions and defaults. The main description adds no further parameter-level semantics, so the baseline of 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?

The description uses a specific verb with a clear resource: 'Use for municipal building, property, and code-violation research in supported jurisdictions.' It also names what this tool is not for, STR licensing and restaurant health inspections, which distinguishes it from relevant sibling tools even without opening their 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?

It explicitly states when to use the tool, when not to use it, and points to alternatives: 'Do not use for STR licensing or restaurant health inspections; choose the corresponding permit or inspection tool.' An agent can route correctly based on this guidance alone.

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

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

The description goes well beyond the sparse annotations by revealing that it starts an Apify Actor, consumes caller usage via APIFY_TOKEN, may wait up to 60 seconds, returns at most 1,000 rows, and does not modify government records. This meaningfully adds cost, latency, limit, and side-effect information that 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?

The description is three tight sentences with no filler. Purpose is front-loaded, exclusions come second, and behavioral constraints are concentrated in one dense final sentence. Every clause contributes useful information.

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

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

For a tool with 7 optional parameters, the description covers the key operational facts: scope, exclusions, auth, cost, latency, row limit, and non-modification. The rich input schema fills in jurisdiction options and parameter details. The only gap is absence of output row structure, but no output schema exists and the description still gives a useful high-level output expectation.

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 itself already gives rich parameter explanations including date patterns, enum values, defaults, and bounds. The description adds no parameter-specific semantics, but since the schema carries the load, the baseline score 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?

The description opens with a specific verb and resource: 'Use for official restaurant inspection scores, violations, and facility-history research in supported jurisdictions.' It also explicitly excludes related areas ('Do not use for general property-code violations or childcare inspections'), which distinguishes it from sibling tools such as property-violations and childcare licensing.

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 clearly states when to use the tool and gives explicit negative guidance for property-code violations and childcare inspections. It stops short of naming the exact alternative sibling tools, but the intended routing is clear enough for an agent.

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

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

The description discloses important side effects and constraints not inferable from annotations: starts the bound Apify Actor with the caller's APIFY_TOKEN, may consume Apify usage, waits up to 60 seconds, returns at most 1,000 rows, and does not modify government records. This aligns with the annotations (readOnlyHint=false, openWorldHint=true) and adds meaningful operational context.

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 purpose, then alternative, then operational caveats. It wastes no words, but the unexplained phrase 'Address mode' and the dense behavioral list make it slightly less crisp than it could be.

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 must explain return values. It says 'returns at most 1,000 source-linked rows' but does not describe the row structure, pagination, failure modes, or meaning of 'source-linked.' The undefined 'Address mode' and the 31-vs-29 source mismatch further reduce completeness.

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 tool description references 'Address mode' and 'address, permit-ID' research, but no schema parameter accepts an address or permit ID, and 'Address mode' is not defined in the schema. This creates some ambiguity rather than clarifying parameter usage.

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

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

The description clearly states the tool's function: address, permit-ID, or jurisdiction research across US short-term-rental permit sources, and distinguishes it from the Florida DBPR sibling. However, it claims '31 supported' sources while the schema enum lists 29 cities/counties, creating a minor factual discrepancy that could confuse an agent.

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 ('Use for address, permit-ID, or jurisdiction research') and names the specific alternative for Florida statewide licenses ('use fl-dbpr-vacation-rentals instead'). This is clear routing guidance with no ambiguity.

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?

Discloses significant behavioral traits beyond annotations: it starts an Apify Actor using the caller's APIFY_TOKEN, may consume Apify usage, waits up to 60 seconds, returns at most 1,000 rows, and does not modify government records. This is especially valuable given readOnlyHint is false, clarifying that the operation has costs and side effects but is not destructive to source data.

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 with no filler. The first sentence front-loads the core use case and sibling distinction; the second compactly lists the behavioral constraints. Every clause adds 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?

Covers purpose, routing, side effects, timeout, result cap, and non-modification of records. With no output schema, it could go slightly further on the exact row shape or fields returned, but 'source-linked rows' gives a reasonable baseline for an agent to proceed.

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 detailed parameter descriptions for all four fields, so the baseline is 3. The description adds value by stating the hard result cap of 1,000 rows, which is not visible in the schema and directly affects how maxRecords should be interpreted.

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 scope (Texas-only) and data types (childcare operation, inspection, and deficiency evidence), and explicitly distinguishes itself from the multistate sibling tool. The title and resource are clearly differentiated 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 when to use this tool (Texas-only evidence) and names the exact alternative for multi-state research: multistate-childcare-licensing. This gives an agent clear routing guidance with minimal 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?

The annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds concrete behavioral context by naming what gets read and explaining that a positive waitSecs waits for a terminal state, which goes beyond the annotations. No contradiction with 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?

The description is two sentences with no fluff. The primary read purpose is front-loaded, and the second sentence adds a meaningful behavioral caveat about waitSecs without repeating the schema.

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 read-only tool covered by strong annotations, the description adequately conveys what is read and the waiting behavior. There is no output schema, so a fuller return-format description could help, but the listed fields and annotations make the tool usable without significant gaps.

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?

Both parameters are fully documented in the input schema, so the baseline is 3. The description adds only modest value for waitSecs by noting the positive-value wait behavior, while runId semantics remain exactly as in the schema.

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

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

The description clearly states the specific verb 'Read' and the resource 'Actor run', and enumerates the data read: status, storage identifiers, summary, and next step. It is unambiguous about what the tool does, but it does not differentiate it from sibling tools like get-dataset-items or get-key-value-store-record.

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?

No guidance is given for when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The only usage-related note is the waitSecs parameter behavior, which is parameter-level rather than tool-selection 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: the dataset must be caller-owned, pagination is bounded, and field selection is optional. This helps an agent understand scope and limitations without contradicting 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 sentence with no filler, front-loaded with the core action and resource. Every phrase carries meaning: 'Read', 'caller-owned', 'bounded pagination', and 'optional field selection' all add useful information without 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?

The tool has 8 parameters, very low schema coverage, and no output schema, yet the description is only one sentence. It does not explain parameter semantics, return shape, pagination behavior, or how field selection/omission works. This is not complete enough for a tool of this complexity.

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 13%, with only datasetId described. The description mentions 'bounded pagination' and 'optional field selection' but does not explain the meanings of limit, offset, fields, omit, flatten, clean, or desc. With this low coverage, the description needed to compensate and did not.

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 ('Read'), a specific resource ('result rows from a caller-owned Apify dataset'), and two distinguishing capabilities ('bounded pagination and optional field selection'). It clearly differentiates this tool from siblings like get-key-value-store-record and get-actor-run, which read different resource types.

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: this tool is for reading result rows from a dataset the caller owns. It does not explicitly name alternatives or exclusion conditions, but the caller-owned and dataset-row scoping are enough to guide an agent toward correct use versus the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the useful 'caller-owned' scoping limitation, but it does not disclose behavior for missing records, response shape, or any other runtime details. With annotations carrying most of the safety burden, this is adequate but not rich.

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

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

The description is a single front-loaded sentence with no filler. It states the verb, object, and key scoping constraint efficiently, making it easy for an agent to parse quickly.

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

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

For a simple two-parameter, read-only tool with full schema coverage and safety annotations, the description provides enough context to select and invoke the tool correctly. It could additionally mention what happens when a requested record does not exist, but that is not essential for basic correct use.

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 both keyValueStoreId and recordKey are already documented in the input schema. The description does not add additional semantic detail beyond the schema, so it meets the baseline but no more.

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 specific verb ('Read') and names the resource ('key-value store record'), adding the important constraints 'one exact' and 'caller-owned.' This clearly distinguishes it from sibling read tools like get-dataset-items and get-actor-run, which address different Apify resources.

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: use this when you need exactly one record by exact key from a caller-owned Apify key-value store. It does not explicitly name alternative tools or exclusion conditions, but the resource scope is specific enough that an agent can identify the right situation.

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