AgentData

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

Annotations already establish readOnlyHint=true, destructiveHint=false, openWorldHint=false. The description adds real behavioral context beyond them: the call is free, is not counted against the allowance, and its output varies by whether an API key is present. It stops short of describing response shape or failure modes, which keeps it out of the top band.

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 that front-loads the usage trigger and then lists the returned metrics in a compact clause. No filler, no repetition of the title or annotations.

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 telling the agent what comes back, and it does so by enumerating the three counters. Combined with the free/not-counted note and the auth-conditional behavior, an agent has everything needed to call this correctly before a large task.

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 schema has nothing to document and the baseline is 4. The description correctly implies a parameterless call with its conditional 'with an API key' phrasing, adding the only parameter-adjacent nuance that exists.

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 concrete resource (today's allowance) and enumerates exactly what is reported: requests in the current 5-hour window, distinct companies today, and contact reveals with an API key. This is clearly distinguishable from the sibling lookup/search tools, which all retrieve entity data rather than account consumption.

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 usage trigger: 'Use this before a large task,' which tells the agent when to call it. It does not name alternatives or exclusions, but the sibling tools (find_people, lookup_company, search_companies) serve wholly different purposes, so no routing ambiguity exists.

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 declare readOnly/non-destructive/openWorld, but the description adds the key behavioral facts an agent cannot get elsewhere: unauthenticated calls return only the first 20 matches with the last 5 withheld, email addresses are omitted without an API key, and narrowing filters is the way to surface the right people in that first page. That is substantial disclosure beyond the structured fields.

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, purpose first, then capability, then the practical limitation and workaround — well front-loaded with no filler. The final sentence is long and slightly restates the page-limit constraint, costing a little tightness.

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, yet the description compensates by enumerating the returned fields and the truncation behavior; combined with 9 params at high schema coverage, an agent has everything needed to invoke and interpret a result.

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 89% schema description coverage the baseline is 3, but the description names the filter dimensions (domain, name, title, seniority, department, sector, B2B/B2C) and hints at combinability with a concrete example ('domain plus a title'), which goes slightly beyond the per-field schema text.

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 ('find_people' -> people at a company or in a role) and enumerates exactly what is returned: names, job titles, seniority, department and LinkedIn URLs. This clearly distinguishes it from search_companies/lookup_company, which operate on companies rather than people.

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?

Opens with an explicit when-to-use trigger ('Use this when the user wants people at a company or in a role') and gives a tactical guideline for narrowing filters ('for example a domain plus a title'). It never names the sibling it is not, so an agent must infer the boundary against search_companies and lookup_company.

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 read-only/non-destructive/open-world, and the description adds real behavioral context on top: results are newest-first, 'empty result means none recorded yet, not that none happened' (crawl-dependent latency caveat), and no PII is exposed. The empty-result caveat is exactly the kind of non-obvious behavior that prevents misreads.

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?

Dense and front-loaded: the trigger condition leads, followed by the parameter routing and the operational caveats. Every sentence carries information, though the multi-clause opening and trailing caveats make it slightly heavier than ideal.

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 9-parameter, all-optional tool with no output schema and 89% schema coverage, the description covers trigger, routing, pagination ordering, and the empty-result interpretation. It does not discuss how to paginate with limit/offset or what a signal record contains, but these are largely covered by the schema or non-essential for correct invocation.

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 89%, so the baseline is 3 and the schema already documents most parameters well. The description adds intent-level semantic value by mapping the user's question to the moved_from/moved_to parameters, which is more than the schema alone conveys about how to drive the tool.

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 — 'which companies recently started, stopped or switched using a technology' — with concrete examples (left Intercom, adopted HubSpot) and expands scope to growth and hiring changes. This is clearly distinct from siblings like get_technologies (current stack) and lookup_company (single-company lookup).

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 triggers on a user question pattern and tells the agent how to route it ('set moved_from or moved_to'), plus notes the broader growth/hiring coverage. The 'no API key needed; no contact reveals' note also tells the agent when this is the viable choice for contact-free queries.

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/openWorld/non-destructive, and the description adds substantive context beyond them: page size (20), the company_count vs. listed_count distinction with the exact stop condition ceil(listed_count / 20), default and maximum index size, and the fact that it works without an API key and reveals no contacts.

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?

Dense but front-loaded: the trigger condition leads, then the slug/no-slug behaviors are laid out parallel, then edge details. Every sentence carries operational information; nothing is filler.

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

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

There is no output schema, so the description compensates by naming the returned fields (company_count, listed_count) and explaining pagination math. With auth requirements, result semantics, and mode behavior all covered, an agent has everything needed to call 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 coverage is 100%, so the baseline is 3, but the description goes further: it specifies slug casing and hyphenation with concrete examples (google-analytics, shopify) and clarifies that 'page' only applies when a slug is given and 'limit' only when it is not, disambiguating the conditional use of 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?

States a specific verb and resource ('which companies use a particular technology', 'which technologies are most used') and explicitly splits the two behaviors by presence or absence of a slug. An agent can distinguish this from siblings like search_companies or lookup_company 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?

Opens with an explicit trigger ('Use this when the user asks which companies use X') and enumerates example technologies. It also tells the agent precisely which mode applies with vs. without a slug, leaving no ambiguity about when to call it.

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 mark it read-only, non-destructive, and open-world, but the description adds substantial behavioral context: API-key gating for personal emails and names, public-page data without a key, on-demand crawling for unprofiled domains, retry timing, and no charge for that crawl.

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 usage case is front-loaded in the first sentence, and the description is broken into logical concerns: use case, returned data, API-key limits, alternatives, and crawl behavior. It is thorough rather than wasteful, though the long inventory of returned fields makes it denser than ideal.

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 and one required parameter, the description carries the full burden of explaining return values, access limits, and crawl behavior. It is complete enough for an agent to call the tool correctly and interpret what comes back.

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 domain parameter is already documented with format examples. The description adds context about when the domain is known and what happens if the domain is unprofiled, but it does not add syntax or format meaning beyond 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 states a specific verb and resource: look up one specific company by its website domain. It also distinguishes the tool from siblings by telling the agent not to use it to find a company by name and to use search_companies instead, and to use find_people for names at a company.

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 explicit when-to-use guidance: when the user asks about one specific company and the domain is known, such as account research before a call. It also gives clear alternatives and exclusions, including search_companies for finding a domain by name and find_people for people names.

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 and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: result shape (up to 20 summaries per page with email counts per company), that no API key is needed, and that no contact data is revealed. It stops short of describing rate limits or sort/ordering behavior.

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, front-loaded with the primary lookup use, then the list-building use, then the sibling routing. Every sentence carries distinct information; nothing is 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 9 optional parameters, no output schema, and read-only annotations already present, the description fills the remaining gaps: it explains the paginated return payload and the email-count field, and it clarifies that query short-circuits the filters. 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% and the enum labels are already documented, so the schema does the heavy lifting. The description adds only a light restatement of the query-vs-filter exclusivity that the schema itself already states, so the baseline 3 is correct.

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

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

States a specific verb (find/build a list) over a specific resource (companies), and enumerates the exact filter dimensions the tool searches on. It also names what it is not — lookup_company and get_technologies — so the agent can distinguish it from siblings 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?

Gives explicit when-to-use branches (find one company by name/domain vs. build a list by sector, model, B2B/B2C, tech, country) and pairs each with the correct alternative (lookup_company for a full single record, get_technologies to page all companies using a tool). Routing is unambiguous.

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