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.