StartupHub.ai

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

Annotations declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, but the description advertises calling arbitrary third-party APIs with 'METHOD /path' plus body and gives the example 'book the reservation' — plainly state-mutating and open-world. The description directly undercuts the safety annotations an agent would otherwise rely on for approval decisions.

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?

Purpose is front-loaded and every clause adds information (mode formats, follow-up tool, credits, account requirement). It is telegraphic and run-on ('REST: ... MCP: ... Chat: ... Agent: ...'), which costs a little readability but not content value.

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 10-parameter generic proxy with no output schema, it covers billing, the free-account prerequisite, the task_id follow-up path and optional provider key. It does not cover error behavior, rate limits, or whether methods like GET vs DELETE behave differently — relevant given the destructive potential.

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 30%, but the description compensates by explaining the operation string per mode (REST 'METHOD /path', MCP tool name + arguments, chat model id + messages, agent task), how path/query/body and label apply, and when provider_key is needed. Remaining gaps are structural detail of the free-form body/query objects, which the schema types only loosely.

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 (call any API, MCP server, chat endpoint or agent listed on StartupHub) and enumerates the four invocation modes with their operation formats. An agent can distinguish this from find_apis (discovery) and get_api_task (follow-up) 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 routes discovery to find_apis, long agent tasks to get_api_task, and constrains provider_key to 'only when the listing needs your own key'. Lacks an explicit statement of when not to use it or what happens for unsupported listing types, so not a full 5.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds one useful non-annotation fact, the free-account requirement, but says nothing about irreversibility or what happens to the watch after cancellation. It clears the lower annotated bar without adding much.

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, action first, prerequisite input second, account requirement last. Nothing is padded or repeated from structured fields.

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

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

For a one-parameter destructive cancel with no output schema, the definition covers purpose, input provenance, and auth. What remains — confirmation semantics, behavior on a bad id — is nice-to-have rather than essential.

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 0%, so the description must carry the burden — and it does, specifying that 'id' is the watch identifier and that it comes from list_monitor_watches. That is meaningful semantics beyond the bare string type, though it omits format expectations.

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 ('Stop') and resource ('company watch'), which cleanly separates it from create_monitor_watch and list_monitor_watches. An agent can identify the operation 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?

It names the sibling that supplies the required input ('Pass id from list_monitor_watches') and states the account prerequisite, which is genuine routing guidance. It does not describe when *not* to cancel, but there is no obvious alternative tool, so the gap is minor.

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 establish readOnly/openWorld/non-destructive, so the bar is lower. The description adds real prerequisite context beyond the annotations: an API key is required and a free StartupHub.ai account is needed, warning the agent about auth/credential failure modes. It stops short of noting rate limits, credit consumption, or third-party (Ahrefs) data latency.

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 fragments, front-loaded with the returned metric. Very little waste, though the final two sentences both convey 'you need credentials,' a mild 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?

For a single-parameter read tool with no output schema, the essentials are covered: what the value is, its scale, and the credential requirements. The one substantive gap is sibling disambiguation against check_effective_domain_rating.

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 schema coverage is 100% — the schema already documents it in more detail ('Domain or URL, e.g. example.com') than the description's bare 'for a domain'. Baseline 3 applies since the description adds no syntax or normalization rules.

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+return metric: 'Ahrefs Domain Rating, 0 to 100, for a domain.' An agent knows exactly what comes back. It does not, however, distinguish itself from the near-identical sibling check_effective_domain_rating, which is the main ambiguity here.

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

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

There is no guidance on when to use this rather than check_effective_domain_rating, check_trust_reputation, or scan_company_technology. The only 'guidance' offered is prerequisite-related (API key, account), not situational.

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 (readOnlyHint, destructiveHint: false, openWorldHint), so the bar is lower. The description nonetheless adds genuinely useful operational context: a 30-60 second latency expectation, an API-key requirement, and a free StartupHub.ai account prerequisite.

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 definition is compact and front-loads the core metric definition before latency and auth prerequisites. Every clause carries information; no 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?

For a read-only tool with full schema coverage and annotations declaring safety, the description supplies what the structured fields cannot: latency, auth, and account prerequisites. Only the missing sibling routing against check_domain_rating keeps it from being 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 the schema already documents both 'domain' and 'keyword' (including the default-from-homepage-title behavior). The description adds no parameter-level meaning beyond the schema, which is the baseline-3 case.

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 resource and metric: a 0-100 'effective' domain rating measuring realized visibility, positioned against Ahrefs Domain Rating. It is clear what the tool returns, but the differentiation from the near-identically named sibling check_domain_rating is only implied by 'set next to Ahrefs Domain Rating' rather than stated.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative routing, despite the sibling check_domain_rating being easily confused with this tool. The phrase 'set next to Ahrefs Domain Rating' hints at a complementary relationship but never tells the agent which of the two tools to pick or why.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a latency expectation ('Often takes 30 to 70 seconds') and auth requirements (API key, StartupHub.ai account). These are the kind of traits an agent needs for planning.

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?

Very short and front-loaded: purpose first, then parameter/latency/auth facts. Every fragment carries information. The telegraphic style is slightly abrupt but wastes nothing.

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 names the return content (PageSpeed scores and Core Web Vitals) and covers latency and auth prerequisites. For a simple 2-parameter read-only tool this is nearly complete, though it never confirms what the response shape or units look like.

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 parameters are already documented. 'strategy is mobile or desktop' merely restates the enum, and 'for a public URL' adds only a small constraint (URL must be public). Baseline 3 is appropriate when the schema carries the parameter detail.

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 (speed test/check) and resource (PageSpeed scores and Core Web Vitals) and scopes it to 'a public URL,' so an agent immediately knows what it returns. No sibling in the list offers a competing speed test, so sibling differentiation isn't required. Clear but not as sharp as a 5 would demand.

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

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

Usage is implied: testing the speed of a public URL. Prerequisites ('Requires an API key. Needs a free StartupHub.ai account') are given, which helps an agent know if it can call the tool. However, there is no explicit when-to-use/when-not guidance or named alternatives, so this is minimum-viable.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds meaningful context beyond that: the auth requirement (API key plus account) and the composition of the score (security, privacy, public record), which is what the agent gets back.

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, front-loaded sentences with no filler; the output semantics lead and the prerequisites follow. Slightly telegraphic ('Trust and Reputation.' as a header fragment), but nothing 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 carries the return-value burden and does state what the score is and its range. Params and safety are covered by schema and annotations; the only real omission is how this differs from the sibling domain-rating tools.

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 only two parameters, so the schema already documents 'domain' and 'company' fully. The description adds no format, syntax, or disambiguation guidance beyond the schema, which is the expected baseline when the schema does the work.

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 resource (a domain) and the output ('A 0 to 100 score from security, privacy, and public record'), which is more specific than a bare 'check trust'. However, it never distinguishes itself from the closely named siblings check_domain_rating and check_effective_domain_rating, so an agent can't tell from the description which score tool to pick.

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 supplies prerequisites ('Requires an API key', 'Needs a free StartupHub.ai account') but no when-to-use guidance and no routing away from the near-identical sibling rating tools. It tells the agent how to be allowed to call it, not when to choose 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?

Goes well beyond the annotations (which only say non-readOnly, non-destructive, closed-world): it discloses the credit cost per call, the ~15 second latency, the async 'building' status semantics, the account requirement, and the equivalent REST endpoint. That is exactly the operational context an agent needs before invoking.

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 outcome, return values and polling instructions are front-loaded and every sentence carries operational weight. It is dense and a little run-on in the middle polling sentence, but there is 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, and the description fully enumerates the return shape (image_url, editor_url, segments with companies and profile links, map spec JSON, optional public link). Combined with latency, async status and auth requirements, an agent has everything needed to call and follow up 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 schema already documents both params; the baseline is 3. The description still adds value by giving example prompt phrasings ('fintech startups in London', 'AI coding assistants split by use case') and restating the publish:true behavior in terms of a public link.

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 ('Build a startup market map from a plain-language request') and immediately gives concrete example prompts. It is clearly distinguishable from siblings like get_market_map, edit_market_map, style_market_map and publish_market_map, which are all referenced or implied as separate steps.

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 routes the agent: when status is 'building', follow with get_market_map (map_id) every few seconds until 'done', and explicitly warns NOT to call create_market_map again. It also states the account prerequisite and that the interactive Claude view polls on its own.

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 flag readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds genuinely useful behavior beyond that: API key requirement, free-account prerequisite, and that frequency is clamped to the plan. It stops short of describing what happens on creation (e.g., returned watch identifier).

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

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

Front-loaded fragments that each carry information, no filler. The telegraphic style ('Monitor. Watch...') is terse but readable and efficient.

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 4-parameter mutation with no output schema, the description covers inputs and prerequisites well, but says nothing about the result of creating a watch (ID, confirmation, error behavior). Adequate but with a clear gap for a creation tool.

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

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

Schema coverage is 75%, and the description compensates by naming the enum values (weekly/daily/12h/4h), specifying the https-only constraint on webhook_url, and clarifying that signals is optional. 'Clamped to the plan' adds a constraint absent from 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?

States a specific verb and resource ('Watch a company site and get alerts when public signals change') and clearly positions itself against siblings like cancel_monitor_watch and list_monitor_watches. An agent can identify it 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?

Gives prerequisites ('Requires an API key', 'Needs a free StartupHub.ai account') which imply when it can be called, but never states when to use it versus alternatives such as list_monitor_watches or conditions for creating a watch. Usage is implied rather than explicit.

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 genuinely useful context beyond that: the auth requirement ('Needs a free StartupHub.ai account') and an equivalent REST endpoint. It omits rate limits and cost, but adds real value on top of 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?

Front-loaded with the core action and efficient throughout, with each sentence carrying distinct information (scope, accepted inputs, dossier contents, breadth, endpoint, auth). Slightly verbose in enumerating dossier components, but 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?

There is no output schema, and the description compensates by enumerating the dossier contents (company facts, funding, people, technographics, social/web presence, AI signals). Combined with annotations and the auth note, an agent has enough 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 coverage is 100% and the single parameter is fully self-documented; the description's list of accepted input types simply restates the schema. Baseline 3 is appropriate since it adds no syntax or format detail 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?

States a specific verb+resource ('run a deep-intelligence lookup on any entity') and explicitly positions it as 'the widest single call in the catalogue,' which cleanly distinguishes it from focused siblings like enrich_company, get_startup, or search_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?

It gives clear input context (name, company, domain, LinkedIn URL, or email) and hints at breadth via 'widest single call,' but never explicitly says when to prefer this over the many narrower siblings such as enrich_company or get_company_funding. Usage is implied rather than routed.

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 the safety profile (readOnly, non-destructive, openWorld), and the description adds rich context on top: billing is triggered only when an address is found, first call may be slow with a documented retry pattern, and it previews the return shape (verified address, confidence score, reach note). That is exactly the behavioral disclosure annotations cannot supply.

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

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

Front-loaded with purpose, then inputs/outputs, cost, and retry behavior — each sentence earns its place. The closing pairing sentence is longer and more narrative than the rest, but it does route an agent toward a real workflow.

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 still explains what comes back (address, confidence score, reach note), the cost model, the latency/retry quirk, and the inputs. An agent has everything needed to invoke it correctly and interpret the 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?

Schema description coverage is only 25% (only 'role' documented), so the description carries most of the burden and does describe the three required inputs semantically. It also adds nuance for 'role' (founder/CEO first-name matches rated high confidence), though it omits format details like whether the domain should include scheme/www.

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 with scope: 'Find a real, deliverable professional email for a person at a company' and specifies the required inputs (first name, last name, company domain). It implicitly separates discovery from adjacent siblings like validate_email and enrich_email, but never names them, so the differentiation is left to inference.

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 usage context: pass first + last name + domain, charges 1 credit only on success, retry with identical args if no matches come back, and a pairing workflow with scan_agent_readiness. Strong guidance, but no explicit when-NOT-to-use or an alternative for the same task (e.g. validate_email for an address already in hand).

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?

Goes well beyond annotations: changes are saved in place and surface on the public page, the return shape mirrors create_market_map with a status field requiring polling, and billing is disclosed (one credit only when companies are added; style/layout edits free). It also names a concrete removal example ("remove Acme"), which is consistent with destructiveHint=true and makes the destructive surface tangible.

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 opening clause front-loads the capability and the example instructions are the highest-value content. It drifts into a long run-on with billing and account requirements appended, but each sentence carries non-redundant 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?

With no output schema, the description compensates by describing the return shape (same fields as create_market_map, including status) and the async polling requirement. Auth, cost, and persistence are all covered, leaving nothing an agent needs before calling.

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 states where map_id comes from and that long pasted lists are fine with the instruction above them. The description's example instructions add flavor but no constraints or format rules beyond the schema, so it sits at the 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 ("Change a market map the account owns or co-authors, in plain words") and immediately distinguishes itself from create_market_map and get_market_map by naming both as the source of map_id. The example instructions make the nature of the operation unmistakable.

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 routes the agent: map_id comes from create_market_map or get_market_map, and when status is 'building' the agent should poll get_market_map until 'done'. It lacks an explicit exclusion statement (e.g. don't use this to create a new map or to reorder outside style/layout), so it falls just short of a 5.

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=false, openWorldHint=true, destructiveHint=false, and 'build a profile' is consistent with a non-read, open-world operation. The description adds value annotations do not carry: the account prerequisite and the concrete set of returned attributes.

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 core action, then the return shape, then the prerequisite. Every sentence carries information an agent needs; no filler.

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

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

With no output schema, the description correctly enumerates the returned fields; with annotations covering safety, the remaining burden is auth/cost context, and the free-account note covers the main part. It does not mention credit consumption or latency, which neighboring usage/credit tools suggest is relevant.

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 0%, so the description is the only source of parameter meaning. It correctly identifies 'name' as required and website/LinkedIn as optional, but adds no format, encoding, or URL-shape guidance and does not explain how the two optional identifiers are combined or prioritized.

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: 'Build a company profile' with named inputs (name, website, LinkedIn URL) and named outputs (description, sector, HQ, founding year, links). It is distinguishable from most siblings, but the description never explicitly contrasts itself with the nearby get_company_by_linkedin / get_startup_by_domain tools, which an agent could plausibly confuse it with.

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

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

Usage is implied by the name/output-fields framing, and one prerequisite is stated ('Needs a free StartupHub.ai account'). However, there is no explicit when-to-use vs when-not guidance and no routing to alternatives such as get_company_by_linkedin or enrich_email, so the agent must infer 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description adds the operational context that matters: cost of 1 profile credit, the requirement of a free StartupHub.ai account, and the full return payload. It stops short of describing failure/fallback behavior when Gravatar or person matching misses, though the 'best available' and 'if person is unknown' phrasing partially covers this.

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

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

Front-loaded with the core contract ('Pass an email, get back: ...') followed by return fields, then use cases, then cost/auth. The colon-delimited return list is efficient, but marketing phrasing ('The killer endpoint for...') and the credit-comparison sentence are slightly padded relative to the informational payload.

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, and the description compensates by enumerating the returned fields in order of importance, plus auth requirement and per-call cost. For a single-parameter read-only enrichment tool, an agent has everything needed to call it and interpret the 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?

One parameter with 0% schema description coverage, so the description carries the burden: 'Pass an email' identifies the input, and the free-provider/local-part discussion implies the expected format (a real address whose domain and local part are parsed). It never spells out format constraints or invalid-input behavior, so it is not fully compensating, but it adds real meaning beyond the bare 'email: string'.

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 (enrich) plus resource (email address) and enumerates exactly what comes back, including name/source, Gravatar profile, mail provider, matched person, startup/investor domain match, name heuristic, and free-provider flag. It explicitly distinguishes itself from the sibling chain get_person_by_email + get_startup_by_domain + get_investor_by_domain, so an agent can pick it without opening other 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?

Names concrete usage contexts (HubSpot/Salesforce auto-enrichment, Gmail/Outlook plugins, lead-scoring pipelines) and explicitly positions itself against the alternative of chaining three sibling tools, with the cost tradeoff stated (1 credit, cheaper than chaining). It even gives a when-not condition: skip company matching when the free-provider flag fires on consumer addresses.

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 and destructiveHint=false, so the safety profile is covered; the description adds meaningful context beyond that, notably that call_through_startuphub consumes your StartupHub key and credits, which is a cost/billing trait not expressed in the schema or 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 tight sentences with zero filler: the first states scope, the second enumerates return fields and highlights the actionable call_through_startuphub URL. Front-loaded and dense, with every clause carrying 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?

There is no output schema, and the description compensates by enumerating exactly what each result contains (endpoint, spec URL, auth type, price per call, operations/tools/models/skills, call_through_startuphub). Combined with a fully documented 3-parameter schema and read-only annotations, an agent has everything needed to call it and interpret the response.

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%, including an enum explanation for every kind value and a default for limit, so the schema carries the parameter burden. The description adds nothing about how query is matched (semantic vs keyword vs company name) or how kind interacts with the returned corpus, so 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?

The description pairs the verb 'Find' with specific resources (APIs, MCP servers, AI agents) and names the source (StartupHub), plus enumerates return fields. It implicitly separates itself from call_api by describing call_through_startuphub as the execution path, though it never names that sibling directly.

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 is only implied — an agent can infer this is the discovery step before call_api, but the description never states when to use it versus search_startups, find_matches, or other lookup siblings, nor does it give any when-not 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the output-shape hint (square and horizontal variants) and says nothing about failure behavior when no identifier is supplied, rate limits, or what form the logo comes back in.

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 front-loaded sentence with zero filler, which is appropriate for the operation. It is terse to the point of under-specification, but it is not padded or disorganized.

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 should explain the return values, and for a lookup tool with two optional input identifiers it should at least address behavior with no input. It omits return format, fallback behavior, and how name vs website combine, leaving real 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?

Schema description coverage is 0% and neither 'name' nor 'website' is documented in the schema, so the description carries the full burden — yet it only vaguely implies a company is identified. It does not clarify precedence between name and website or what happens when neither of the (optional, 0-required) parameters is provided.

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 ... logos') and narrows scope to a company, adding the useful detail that both square and horizontal variants are returned. It doesn't explicitly differentiate from siblings, but the sibling list (email, RSS, trends, funding, etc.) is unrelated, so the risk of confusion is low.

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

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

There is no guidance on when to use this tool versus the siblings, no prerequisites, and no indication of whether a company name, a website, or both are needed to get a result. The agent is left to infer everything about invocation context.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious operational context: an API key is required and a free StartupHub.ai account is needed, plus the result shape includes a 'reason' per match. It stops short of describing pagination, limits, or failure modes.

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 core behavior and then the two input directions. Every clause carries information; there is no restatement of the title beyond the opening label.

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 notes that each match carries a reason, and it covers auth requirements and the bidirectional input rule for a tool whose required enum is undocumented in the schema. It is essentially complete for invocation, missing only volume/limit expectations.

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

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

Schema coverage is 67% and the schema documents id/slug as 'slug or id', but the required 'type' parameter carries no description in the schema. The description supplies exactly that missing semantics: type selects the direction of the match, so the agent knows 'type' is not merely a filter but the determinant of the result set.

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 ('find') and spells out both directions of the operation: startup id/slug in, investors out, and vice versa. This clearly separates it from plain lookup siblings like get_startup or get_investor_by_domain, though it never explicitly names an alternative.

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

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

Usage is implied through the input-direction rule ('Given a startup slug or id...' / 'Given an investor slug or id...'), which tells the agent how to drive the tool. There is no guidance on when to prefer this over search_investors or match_companies_by_domain, and no exclusions or prerequisites beyond the account note.

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 cover the safety profile (readOnly, non-destructive, closed-world). The description adds the operationally critical facts an agent cannot get elsewhere: two parameters are locked and cannot be overridden, there is no offset, results are tier-gated with a 403 on Free, and email visibility is redacted on Pro Lite but full on Pro. It also discloses the return fields (tech stack, RDAP registration date, has_known_emails) with no output schema present.

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?

Well front-loaded: purpose and locked parameters come before the return description and the tier caveats. The 'Inputs: ...' enumeration, however, repeats schema descriptions almost verbatim and is the one block that does not fully earn its space.

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 7-parameter, output-schema-less tool, everything an agent needs is present: what is returned, that the tool is a filtered view of search_startups, how to paginate past it, the auth/tier requirement, and the sibling tools that complete the workflow.

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 already 100%, so the baseline is 3, but the description adds meaning the schema cannot express (the fixed stealth/sort behavior and the no-offset constraint). The per-parameter restatement largely duplicates schema text (defaults, TLD list, with_emails consequence), so it does not fully earn a 5.

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?

Opens with a precise framing: a 'convenience wrapper around search_startups pre-tuned for fresh-stealth deal-flow,' immediately telling the agent both the verb/resource and the exact relationship to the sibling it wraps. It then states the two hard-coded parameters (stealth=true, sort=founded_date.desc) that differentiate this tool from search_startups.

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?

Explicit routing: 'There is no offset; use search_startups with stealth=true to page further' names the alternative and the condition that selects it. It also prescribes a workflow ('Combine with list_startup_team and discover_email to surface the actual addresses') and states the tier gate (Pro Lite+, Free tier 403s) that determines whether the call is even usable.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description layers on what they don't say: it is asynchronous (returns a job id immediately), it costs video credits billed at queue time, it needs an API key, and it requires a StartupHub.ai account. Cost and auth disclosure beyond annotations is exactly the value-add expected here.

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?

Five short sentences, each carrying distinct information (capability, inputs, async return, follow-up, cost/auth). Front-loaded with the outcome and free of 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, and the description compensates by explaining the return contract (job id, then mp4_url via get_article_video) plus the billing/auth preconditions. Nothing an agent needs to invoke and follow through 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%, so every parameter including the format enum and defaults is already documented structurally. The description only echoes the url/text mutual exclusivity that the schema already states, adding no new parameter detail. Baseline 3 applies.

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

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

States a specific verb and dual resource ('Turn an article URL, or a block of text, into a narrated video with captions'), so the agent knows exactly what comes out. It also implicitly separates itself from the sibling get_article_video, which it names as the polling counterpart.

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 end-to-end workflow: call this, capture the job id, then poll get_article_video until status is done, then use mp4_url. The condition selecting the follow-up tool is spelled out rather than 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=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds real value beyond them: it discloses the rate limit ('Free, rate-limited'), the return payload (feed_xml and feed_url), and the notable capability of generating feeds for sites that never had one.

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?

Four short, front-loaded sentences with no filler; the resource and capability come first, return values and constraints follow. Efficient, though the staccato phrasing leaves little room for nuance.

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

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

For a one-parameter read tool with no output schema, the description supplies the missing return-value information (feed_xml, feed_url) and the rate-limit caveat. An agent has what it needs to call and interpret the tool 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?

Only one parameter, and schema description coverage is 100% (the schema already gives the 'Site URL, e.g. https://example.com' example). 'Pass the site url' adds no syntax or format detail beyond the schema, 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?

States a concrete verb+resource ('Build a feed for a site') and adds a distinguishing capability note ('including one that never published a feed'). Sibling tools are all in unrelated domains (email, logo, trends), so no sibling differentiation is needed; the purpose 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?

'Pass the site url' implies the single required input but gives no when-to-use context, prerequisites, or when-not guidance. Adequate but lacking explicit routing or exclusion criteria.

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 readOnlyHint=false and openWorldHint=true, and the description goes well beyond them: it discloses a 5-credit cost with per-tier daily quotas, that rows are found-or-created in the database (a real side effect), the free-account requirement, and the return payload. That is rich behavioral context not derivable from 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?

Front-loads the core mechanic ('Prompt → curated startup list') and keeps each subsequent sentence purposeful (workflows, cost, returns, auth). It is dense and slightly long, but nearly every clause earns its place.

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 still explains the return shape (id/name/slug/logo plus a 'created' count), the credit/quota model, and the account prerequisite. Nothing material an agent needs to call 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%, so the schema already documents limit, prompt, and pasted_list with examples. The description reinforces the prompt-vs-pasted_list choice but adds little syntax or format detail beyond what the schema provides, 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?

States a specific verb+resource ('generate a curated startup list') and explains the mechanism: a prompt runs a Google-grounded search, parses results, and finds-or-creates matching rows. It distinguishes itself from sibling search_startups by emphasizing list generation and DB row creation, and names the downstream /lists/submit step.

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?

Enumerates three concrete workflows (portfolio page from prompt, extract companies from raw text via pasted_list, scheduled refresh via cron) and explicitly states when to use 'pasted_list' instead of 'prompt'. This is the when-to-use routing an agent needs.

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 readOnlyHint=false with destructiveHint=false and openWorldHint=false, so the description usefully adds the non-obvious prerequisites: an API key and a free StartupHub.ai account. It also discloses the return shape (markdown and image_url), which the absent output schema leaves undocumented. It does not mention credit cost or rate limits, so not a full 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?

Five short sentences, front-loaded with the core action and then the required inputs, return values, and prerequisites. Tight and scannable. The two trailing auth sentences ('Requires an API key. Needs a free account.') are slightly redundant with each other.

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 covers return values (markdown, image_url) and prerequisites, which are the main things an agent would otherwise lack. Two optional parameters go unmentioned, but they are self-explanatory enough that this is close to 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 coverage is 50%, and the description adds real value by clarifying content_html accepts 'HTML or the article text' rather than just HTML. However, it names only title and content_html, leaving excerpt and source_url unaddressed in both description and schema. Baseline 3 fits.

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: 'Build a diagram and a short summary from an article.' An agent immediately knows this generates visual+text summary output. It does not explicitly distinguish itself from siblings like generate_article_video or humanize_text, which also transform text, so it stops short of a 5.

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

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

Usage is implied by the input requirement ('from an article'), but there is no explicit when-to-use, when-not, or named alternative among the many generate_* siblings. The agent is left to infer that this is the tool for turning an article into a diagram plus summary.

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 mark this as non-read-only, non-destructive, open-world, so the mutation profile is covered. The description adds genuine context beyond that: credit consumption, an account prerequisite, and a latency-mitigation workflow. It does not describe rate limits or output format details, but with annotations carrying safety the added context is solid.

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, front-loaded with the core purpose, then cost, then the fallback workflow. Every sentence carries non-redundant information 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?

For a 5-param generation tool with full schema coverage and no output schema, the description supplies outputs, cost, auth, and the latency fallback. 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%, with url/tone/length/transcript/include_embed all documented including enum semantics, so the schema does the heavy lifting. The description echoes the transcript parameter through the fallback workflow but adds no syntax or format detail 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 and resource ('Turn a YouTube URL into an article') and enumerates the concrete outputs (title, excerpt, HTML, Markdown), so an agent knows exactly what it produces. It is clearly distinguishable from siblings like get_youtube_transcript and generate_article_video.

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 conditions and alternatives: it costs one credit, requires a free StartupHub.ai account, and if the call is slow the agent should call get_youtube_transcript first, then re-invoke with url and transcript. This is a named fallback with the triggering condition, not implied usage.

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 and destructiveHint=false, so safety is covered. The description adds genuinely useful non-schema context: zero credits debited for own data, auth/account requirement, and that the JSON shape matches the public API and dashboard. It omits anything about row limits or response size, but the cost and auth disclosures are real additions.

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 core capability is front-loaded in the first sentence, and cost/auth constraints land before the speculative workflow list. However, the trailing 'nightly Slack digests, attribution stacks, autonomous bid-tuning, etc.' is promotional padding that doesn't help an agent decide or call 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 carries the return-value burden and does list the key metrics and breakdown dimensions. Cost, auth, and data scope are covered for a read-only tool. Minor gaps remain around result volume/pagination and whether historical days beyond a limit are truncated.

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% — both 'days' (1–365, default 30) and 'ad_id' (ownership constraint, omit for all) are fully documented in the schema. The description's mention of by-placement and by-variant breakdowns describes output dimensions rather than adding meaning to either parameter, 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 ('Live performance for ads owned by your account') and enumerates exactly what the payload contains: impressions, clicks, CTR, daily trend, by-placement and by-variant breakdown. It also names the underlying REST endpoint and dashboard it mirrors, so an agent knows precisely which resource this covers. No sibling tool touches ad performance, so no differentiation is needed.

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 implies usage through example scenarios ('nightly Slack digests, attribution stacks, autonomous bid-tuning') and states the precondition of a free account, but never says when not to use it or which sibling to prefer for related tasks. The agent must infer the fit rather than being routed explicitly.

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 says passing cancel stops the task and refunds credits — a state-changing, side-effecting operation — while annotations declare readOnlyHint=true and destructiveHint=false. That directly contradicts the declared safety profile an agent relies on to decide whether calling is harmless.

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 compact sentences, front-loaded with the core purpose before the control options and the account prerequisite. Dense but nothing is wasted; only the trailing account note could be trimmed or moved to a prerequisite line.

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: it names the state, the agents tried, and the final output. It also notes the free-account prerequisite. Remaining gaps are polling cadence and what states/exit conditions the agent should expect, but nothing essential to invoking it correctly is absent.

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 75%, but the description still adds meaning the schema does not: cancel refunds credits (the schema has no description for cancel at all), reply is specifically 'to answer an agent that asked for input', and task_id/route_id are traced to the tools that produce them. What's missing is guidance on which of task_id/route_id to supply, given neither is required.

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 concrete verb and resource ('Check a long-running task') and immediately identifies the two parameter sources (a task_id from call_api, a route_id from run_agent_task), tying it to the siblings that create the tasks. An agent can distinguish this polling/control tool from call_api and run_agent_task 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?

Gives clear context for when each mode applies: poll for state/output, pass cancel to stop and reclaim credits, pass reply to answer an agent that asked for input. It doesn't state when not to use it (e.g. vs list_my_api or re-invoking run_agent_task), so it falls just short of explicit 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 only cover the safety profile (readOnly, non-destructive, open-world). The description goes well beyond: refresh cadence (every 30 minutes), no API key, no cost, the arb criterion (combined cost under $1), and an explicit caveat that results are informational and resolution rules/fees/withdrawal terms must be verified before trading.

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

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

Front-loaded with the core purpose, then return shape, then the parameter, then the disclaimer — a logical order with almost no filler. It is dense and a little long, but each clause (roi_pct, profit_per_dollar, trade URL, refresh interval) carries information an agent needs.

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 carry the return contract — and it does, naming the per-opportunity fields (venue, price, direct trade URL, combined cost, when the arb last opened) plus the derived arb metrics. Combined with annotations and the fully documented parameter, nothing an agent needs to invoke and interpret this tool 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 parameter's description already explains that true filters to live arbitrages and false returns the full matched board. The description restates that behavior but adds no syntax or edge-case detail beyond the schema, so 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 ('Live cross-venue prediction-market arbitrage board') and precisely what it returns: the same events priced on Polymarket, Kalshi/Robinhood, and PredictIt side by side. It is unmistakably distinguishable from every sibling tool (email, logo, trends, funding, etc.).

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?

Identifies the target caller ('Built for trading agents that poll for tradeable spreads') and the condition for the only parameter (arbs_only=true for live arbs only). There is no explicit when-not guidance or named alternative, but no sibling overlaps this space, so no alternative routing is needed.

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 and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it is a polling operation, what it returns (status, progress, mp4_url), and the auth requirement (free StartupHub.ai account).

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 with zero filler, front-loading the core action (poll) ahead of return details and the account requirement.

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 naming the return fields (status, progress, mp4_url) and the completion condition (status is done). Combined with the sibling workflow link and auth note, an agent has everything needed to invoke and interpret this call.

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?

There is a single parameter with 100% schema description coverage, where the schema already states 'jobId from generate_article_video.' Per the baseline for high coverage, the schema carries the parameter semantics and the description adds nothing new.

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 (poll) and resource (an article-to-video job), and explicitly ties itself to the sibling that creates such jobs (generate_article_video). An agent can distinguish this from generate_article_video 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?

Gives clear context: use this to poll a job that generate_article_video started. This establishes the create-then-poll workflow, but it doesn't state when to stop polling or what to do on non-done statuses.

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 establish readOnly, non-destructive, open-world behavior, so the description only needs to add context. It does: it discloses an authentication/account prerequisite and the equivalence to POST /api/v1/companies/by-linkedin, which is useful for agents that know the REST surface. It does not mention rate limits or caching, hence not 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 short sentences, front-loaded with what the tool does and what it returns, followed by the endpoint equivalence and the account requirement. Every sentence carries information, though the REST-endpoint sentence is only useful to a subset of agents.

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 naming the returned enrichment fields (funding, founders, sectors, score, domain, technographics) and flagging the auth requirement. What remains unstated is failure behavior for unknown or invalid LinkedIn URLs, which would round this out.

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?

There is one parameter with 100% schema description coverage and an example URL, so the schema carries the full burden. The description adds nothing about URL format, variants, or handling of non-canonical LinkedIn URLs, so 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?

The description uses a specific verb pair ("resolve" + "enrich") on a named resource (company) keyed by LinkedIn URL, and enumerates the enriched fields. The LinkedIn-URL input modality implicitly separates it from siblings like enrich_company or get_startup_by_domain, though no sibling is named outright.

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

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

Usage is implied by the input type (you have a LinkedIn URL, so you use this tool), and it notes the prerequisite of a free StartupHub.ai account. However, it never states when to prefer this over enrich_company, match_companies_by_domain, or get_startup_by_domain, which is the real routing decision an agent faces.

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 establish readOnly, non-destructive, closed-world behavior, so the description only needs to add context. It does: it discloses the data source (our enrichment graph), the auth/account requirement, and the REST-endpoint equivalence. It does not cover pagination, rate limits, or failure behavior when a domain is unknown, so it is not a 5.

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

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

Two sentences, front-loaded with the capability and return fields before the supporting details. The REST-endpoint and account-requirement clauses each earn their place, though the endpoint equivalence is only marginally useful to an agent.

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-shape burden and does so by enumerating the fields returned. Combined with the auth prerequisite and data-source note, an agent has enough to call this correctly; only edge-case behavior (missing/private company) is unaddressed.

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% for the single required 'domain' parameter, so the schema already carries the semantics. The phrase 'by domain' adds nothing beyond the schema, making the baseline 3 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 names a specific resource (company funding) and enumerates exactly what it returns: total raised, rounds, latest round, investors, and dates. That is far more concrete than a bare 'get funding'. It does not, however, distinguish itself from near siblings like get_startup_funding_history or query_funding, so it falls short of a 5.

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

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

It states a real prerequisite ('Needs a free StartupHub.ai account') and pins the tool to a domain-keyed lookup, which helps an agent decide it can call this at all. But it gives no guidance on when to prefer this over get_startup_funding_history, query_funding, or get_investor_by_domain, leaving the routing decision 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=true, openWorldHint=false and destructiveHint=false. The description adds genuinely useful context beyond them: it is a live-data signal ranked by velocity, maps to a specific REST endpoint, and requires a free StartupHub.ai account (an auth prerequisite the agent would not otherwise know). Missing only rate-limit/pagination 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 purpose and output shape, then usage framing, then auth/endpoint notes. Every sentence carries weight, though the REST-endpoint equivalence is marginally useful for an agent.

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 two-param, read-only retrieval tool with no output schema, the description adequately conveys what is returned (companies ranked by velocity, with counts and links) and the account requirement, while annotations cover the safety profile. Pagination behavior is not addressed, keeping it below a 5.

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 limit (1–100, default 50) and period ('day'/'week'/'month') are fully documented in the schema. The description adds no syntax or format detail 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 ('companies actively posting roles, ranked by open-role velocity') and describes the output shape (counts and links). The hiring-signal resource is unique among siblings like get_company_funding and get_trends, so an agent can tell it apart without opening a 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?

Provides clear context for when to reach for it ('A growth/traction signal for deal-flow and sales prospecting'), which frames the intent. It does not name an alternative sibling or state exclusions, so it falls short of a 5.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-structured context by disclosing an auth prerequisite ('Needs a free StartupHub.ai account'), which is exactly the kind of behavioral context annotations can't express.

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 purpose, then the differentiation, then the use case and prerequisite. Every sentence carries distinct information with no repetition.

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 one-parameter read tool with annotations covering safety, the description supplies purpose, sibling differentiation, the use trigger, the auth prerequisite, and a hint at the return content ('fund profile / portfolio info'). It stops short of mentioning there is no output schema, but nothing needed 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 0% for the single 'domain' parameter, so the description must carry the load, and it does identify the value as the fund's *website* domain (disambiguating from social handles, which has its own sibling tool). It does not specify format details such as protocol, www, or paths, keeping it below a 5.

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 ('look up a single investor (VC, angel, accelerator) by their website domain') and explicitly distinguishes itself from the near-named sibling get_startup_by_domain ('against the investors table'). An agent can tell it apart from search_investors and get_startup_by_domain without opening a 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 a clear when-to-use trigger: 'Useful when you have a fund's website and want fund profile / portfolio info.' It implies the single-lookup vs. search_investors split but doesn't state exclusions or name the alternative explicitly, so it stops short of a full routing rule.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely new behavioral context: the required free account and the fact that input patterns such as /in/ and /company/ are both accepted, which the agent could not infer from annotations alone.

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 core action, then the format nuance, then the prerequisite. No filler or restated boilerplate; every sentence carries information the agent needs.

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 two-parameter read-only lookup with full schema coverage and no output schema, the description covers the action, input format, and access prerequisite. It stops short of describing what the response contains or what happens on a partial/miss lookup, which would be the remaining 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by clarifying that investor LinkedIn URLs are usually /company/<slug> while both /in/ and /company/ patterns are handled. That directly affects how an agent should format the linkedin parameter.

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 (reverse-lookup) and a specific resource (investor profile) with the identifying input (LinkedIn or Twitter URL/handle). It implicitly distinguishes itself from the sibling get_person_by_social and get_company_by_linkedin by scoping to investors, though it does not name those alternatives 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?

Usage is only implied through the phrase 'reverse-lookup' and the input format; there is no explicit when-to-use guidance or mention of related siblings like search_investors or get_investor_by_domain. The one concrete prerequisite (needs a free StartupHub.ai account) is a useful piece of 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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: access scope ('owns or co-authors'), a cost note ('Free'), an auth prerequisite (free StartupHub.ai account), and the 'building' → 'done' status lifecycle that implies polling.

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 the core action and returned fields front-loaded and the 'when to use' guidance second. The opening clause is slightly dense with returned-field enumeration, but every element earns its place.

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, and the description compensates by naming the returned fields (sections, companies with profile links, image_url, editor_url, public_url). Combined with the auth/cost note and status polling guidance, 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 description coverage is 100% and the single map_id parameter is documented with its provenance (from create_market_map or the ?map= value of a link). The description adds nothing beyond the schema, 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?

States a specific verb and resource ('Show a saved market map') and enumerates its contents: sections, every company with profile link, PNG image_url, editor_url and public_url. It is clearly distinguishable from the mutating siblings create_market_map and edit_market_map.

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 it: to reopen a map before editing it with edit_market_map, and to poll a map whose status is 'building' until it is 'done'. The alternative sibling is named along with the condition that selects 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 declare readOnly/destructive=false, and the description adds real behavioral context beyond that: the call is free and does NOT charge a credit, it requires Bearer auth, anonymous callers get a 401 with a signup link, and it needs a free StartupHub.ai account. These are exactly the operational facts an agent needs and that annotations cannot convey.

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

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

Front-loaded with the resource and returned fields, then cost behavior, then usage guidance, then auth. Every sentence carries weight, though the parenthetical enumeration of all seven credit types is slightly list-heavy for the space it consumes.

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 zero-parameter read tool with no output schema, the description enumerates the returned fields, states the cost and auth requirements, and points to the correct next tool. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the schema carries no parameter semantics to explain and the baseline is 4. The description correctly adds no spurious parameter discussion.

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 the user's current credit balance') and enumerates exactly what is returned (plan tier, limits, used/remaining today and month, never-expiring pack balance). It is immediately distinguishable from data-consuming siblings like discover_email or enrich_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?

Explicit when-to-use ('call before any expensive batch (e.g. 100x discover_email)') and names the follow-up alternative ('if they're low or ask to buy more, follow up with list_credit_packs to get pricing + a checkout URL'). Both the trigger condition and the sibling are given.

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, non-destructive and closed-world, so the safety profile is covered. The description adds two useful bits beyond that: the return shape ('Returns the full person profile') and an auth prerequisite ('Needs a free StartupHub.ai account'), which an agent needs before calling.

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 front-loaded, and each sentence adds new information (workflow pairing, return value, auth requirement). No padding or repetition.

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, single-parameter lookup with annotations covering safety and no output schema, the description supplies purpose, sequencing, return shape, and the account prerequisite. Nothing essential for correct invocation appears to be 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 0% for the single email parameter, so the description must compensate. It only restates that the lookup is 'by their email address', which maps to the parameter but adds no format, normalization, or casing guidance. Minimal compensation for the coverage gap.

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

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

States a specific verb and resource ('Reverse-lookup a person profile') keyed on a specific input ('by their email address'). This cleanly distinguishes it from the sibling get_person_by_social, whose key is a social handle, so an agent can pick correctly 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?

Gives a concrete workflow ('discover_email + validate_email: discover an email, verify it, find the person record'), which clearly tells the agent when this tool fits in a sequence. It stops short of naming exclusions or alternatives like get_person_by_social or search_people, so it is strong context rather than a full when/when-not statement.

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 and destructiveHint=false, so safety is covered. The description adds meaningful behavior beyond that: multi-param 'first match wins' resolution, the fact that it returns the matched platform, and the authentication requirement (free StartupHub.ai account). It is silent on failure/not-found behavior, which keeps this from 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?

Four tight sentences, front-loaded with the core action and followed by input format, resolution rule, return, and auth. Every sentence carries information, though the stacked parentheticals make it slightly dense.

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 states what is returned (full person profile + matched platform). Auth requirements and input flexibility are covered. Only not-found/ambiguity behavior is left unstated for a simple lookup tool.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds cross-parameter semantics the schema cannot express: that multiple handles may be supplied and 'first match wins'. This is real added meaning over the per-param 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?

States a specific verb+resource: 'Reverse-lookup a person profile by any of their social URLs/handles', which is unambiguous and distinct from get_person_by_email. It does not explicitly contrast with the closest sibling, get_investor_by_social, but the 'person' scope is clear from the name and text.

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 specifies which params to pass (linkedin, twitter, or github) and that multiple are allowed with first-match semantics, which is useful context. However, it gives no guidance on when to prefer this tool over get_person_by_email or search_people, leaving alternative selection 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral detail beyond the annotations: that a free StartupHub.ai account is required. It does not, however, describe return format, pagination, or error 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?

Two short sentences that are front-loaded with the purpose, which is good. However the two sentences run together without punctuation ('by slug Needs a free...'), a structural flaw that slightly muddles readability.

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 no output schema and annotations covering safety, the description is adequate but thin. It omits routing to the by-domain/by-funding siblings and any hint of the response shape or limits.

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%, so the description must carry the parameter explanation. It does so minimally by stating the lookup is 'by slug', identifying the key type, but adds no format, casing, or example detail beyond that.

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 (Get) and resource (full profile for a startup) with a scope qualifier (by slug), so the agent knows exactly what it retrieves. It does not, however, distinguish itself from siblings that also read startup data (get_startup_by_domain, get_startup_socials, get_startup_funding_history).

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

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

There is no explicit when-to-use or when-not-to-use guidance, nor any named alternative among the many get_startup_* siblings. The only guidance is the account prerequisite, which is a precondition rather than usage 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine non-structured context: the accepted domain input formats, that it returns the full profile, and that a free StartupHub.ai account is required (an auth prerequisite).

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?

Four short sentences, front-loaded with the core action, followed by input formats, return shape, the alternative tool, and the account requirement. No sentence is redundant with another.

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

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

For a one-parameter read tool with no output schema, the description covers action, input flexibility, result nature ('full profile'), auth requirement and sibling routing. Return-value detail is thin, but with no output schema and readOnly annotations the description is essentially 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 coverage is 0% and the schema only declares domain as a bare string, so the description carries the burden. It does so usefully by enumerating accepted formats (raw URL with path, stripped 'example.com', with or without paths), which is meaning the schema does not convey.

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 ('Look up a single startup by its website domain') and scopes it to a single result. It explicitly distinguishes itself from the batch sibling match_companies_by_domain, so an agent can route 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?

Names the alternative tool and the condition that selects it ('Use match_companies_by_domain instead for batches of 2+ domains'), which is clear routing guidance. It does not, however, distinguish this from other single-entity siblings such as get_startup or search_startups, so full when/when-not coverage is absent.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds value beyond the structured fields by disclosing an authentication prerequisite ('Needs a free StartupHub.ai account'), which is material behavioral context an agent would otherwise not know. It stops short of rate limits or pagination behavior, so not a 5.

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

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

Two sentences with no filler; the returned-field inventory is front-loaded and the usage condition follows. The first sentence is dense to the point of being a run-on, but every clause carries information an agent needs.

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, and the description compensates by enumerating the return payload in detail, including the aggregate summary (total raised, latest round date/series). Combined with the annotation-covered safety profile and the stated account requirement, nothing essential for a correct call 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 0% for the single 'slug' parameter, so the description must carry the burden. It implies the identifier refers to a startup via 'for a startup' and the get_startup cross-reference, but never states the slug's format or where an agent obtains it. This partially compensates for the coverage gap, matching the baseline 3.

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+resource ('Full chronological list of investment rounds for a startup') and enumerates the exact fields returned (amount, series, date, pre/post-money valuation, investor IDs, plus summary totals). It explicitly contrasts itself with get_startup and total_funding, so an agent can distinguish it from siblings without opening a 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?

It gives a clear conditional trigger: 'Use after get_startup if you need round-by-round detail rather than just total_funding.' That is explicit when-to-use plus an alternative. It does not address the other funding-adjacent siblings such as query_funding or get_company_funding, so routing between those and this 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds genuinely useful context beyond that: the credit cost relative to a sibling, the auth requirement, and the exact scope of returned data ('ONLY ...', 'plus HQ').

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 dense sentences, all front-loaded: what it returns first, then the cost/comparison, then the auth requirement. No filler or repetition of the title.

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

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

With no output schema, the description carries the burden of describing return contents — and it does so by enumerating emails, socials, and HQ fields. Cost, auth, and scope are all covered, leaving nothing essential for a 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 0% and the description never explains what 'slug' is or how to obtain it. However, with only a single, well-understood identifier parameter the gap is minor, so a mid-range score 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 (returns) and precisely enumerates the resource contents: contact/partnerships/press emails, social URLs, and HQ city/country. It explicitly distinguishes itself from the sibling get_startup by noting it returns only a subset when you don't need the full row.

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-to-use condition ('when you don't need the full row') and names the alternative (get_startup) along with a cost rationale (1 db credit vs 1 profile credit). It also states the prerequisite of a free StartupHub.ai account.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral context beyond them: it is real-time, sourced from StartupHub.ai's 25k+ startups / 24k+ funding rounds, requires no API key, and returns structured JSON the caller can format. It does not mention rate limits or freshness latency.

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

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

Front-loaded with the core purpose and then the usage conditions, and every clause carries information because there is no output schema to describe the return shape. The opening sentence is dense to the point of being a run-on enumeration, which slightly hurts readability.

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 no parameters, the description carries the full burden of explaining what comes back, and it does so thoroughly (capital, sectors with WoW change, rounds, stage medians, themes, investors, exits). Safety and openness are handled by annotations. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond noting the tool is parameter-free, which it implicitly does.

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 a structured, real-time snapshot of what's happening in the AI startup ecosystem') and enumerates the exact facets returned (capital deployed, sectors, countries, rounds, stage breakdown, themes, investors, exits). This clearly separates it from siblings like query_funding, search_startups, or get_company_funding, which are narrower or entity-scoped.

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 usage contexts: 'Use this when a user asks what's trending in AI/startups, to build an investment thesis, to spot rotations, or for weekly-digest-style summaries.' That is clear positive guidance, but it names no alternatives or exclusions (e.g., when to prefer query_funding or search_investors instead).

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is a polling endpoint, it returns status/progress, and mp4_url only appears when status is done. It omits failure/expiry states, but this is solid added 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?

Three short sentences, zero waste, and the polling purpose plus return contract are front-loaded before the account requirement.

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 contract (status, progress, mp4_url when done) and notes the free-account prerequisite. It is nearly complete; only error/expiry behavior 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 job_id parameter is already documented in the schema as coming from render_youtube_clip. The description only reinforces that provenance without adding format or validation detail, 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 (poll), the resource (a clip render started by render_youtube_clip), and what it returns. An agent can immediately distinguish it from render_youtube_clip and from the other get_* 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?

The description ties usage to a preceding render_youtube_clip call, which is clear context for when to invoke it. It does not, however, state polling cadence, termination conditions, or what to do if the job id is unknown/expired.

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 (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds genuine context the annotations don't: it is deterministic/no-LLM, returns raw caption text, mirrors a REST endpoint, and requires a StartupHub.ai account (an auth prerequisite).

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, front-loaded with the primary action and return payload; each sentence adds a distinct fact (inputs, semantics, endpoint equivalence, auth). The REST-endpoint equivalence line is the weakest, but it is short and not 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 correctly fills the gap by naming the return payload (caption text plus title/channel/duration) and the auth prerequisite. For a 1-parameter read tool that is nearly complete; only error behavior for invalid/uncaptioned videos is unaddressed.

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% for the single url parameter, and the description's list of accepted URL shapes duplicates what the schema already documents. Baseline 3 applies because the schema, not the description, carries parameter 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?

States a specific verb+resource ('Fetch the full transcript plus metadata') and enumerates the metadata fields, so the agent knows exactly what comes back. It only partially differentiates from siblings: the 'No LLM / raw caption text' clause hints at a distinction from generate_youtube_article, but neither that tool nor get_youtube_clip is named.

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?

Acceptable input forms (watch/youtu.be/Shorts/mobile/raw ID) and the note 'for downstream summarization or repurposing' imply a usage context, and the account requirement is a real prerequisite. However, there is no explicit when-to-use-this-vs-generate_youtube_article / suggest_youtube_clips guidance, leaving the routing decision 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?

Adds real behavioral context beyond the annotations: per-call limits (12 paragraphs, 20000 characters), auth requirements, and the guarantee that facts are preserved. Annotations cover safety hints but say nothing about quotas or account prerequisites, so this is a genuine addition.

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?

Four short sentences, well front-loaded with the purpose first and constraints after. Slightly clipped/telegraphic style but every sentence carries information.

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

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

Covers purpose, limits, and prerequisites for a low-complexity single-transform tool with a fully documented schema. The main minor gap is that no output schema exists and the return shape (rewritten text) is not described.

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 'text', 'options', and 'strength' are already documented in the schema with enums. The description adds no syntax or format detail for these parameters, so baseline 3 applies.

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

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

States a specific verb and resource ('Rewrite a passage so it reads as natural prose') with a clarifying constraint ('without changing the facts'). No sibling tool does text rewriting, so it is easily distinguished.

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 operational context — requires an API key and a free StartupHub.ai account — plus size limits, but never says when to choose this versus any alternative or when it is inappropriate. Usage is implied rather than stated.

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 cover the safety profile (readOnly, non-destructive, closed-world), so the description adds genuinely new behavior: no in-MCP purchase path, browser-only checkout, credits never expire, and volume discounts auto-apply. It also sketches the return shape, which is valuable given no output schema 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?

Front-loads the core purpose and keeps the usage trigger and purchase-flow caveat tight. The inline return JSON and hardcoded URL are slightly heavy, but each sentence carries usable information for a tool with no output 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?

With no output schema, the description correctly supplies the return structure (buy_url + pricing tiers) and the credit terms. Nothing an agent needs to call it or relay results to the user 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%, so the baseline is 3, but the description goes further by showing pricing organized as { validate: [...tiers], discover: [...tiers] }, tying the enum values to concrete output categories and clarifying what the 'type' parameter selects.

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 credit pack pricing AND a checkout URL') and expands on the name to include the buy_url, so an agent immediately understands the dual output. No sibling tool overlaps this pricing/credits purpose, so differentiation is implicit but 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 an explicit trigger: surface buy_url on a 402 'credit_limit_exceeded' error, or when the user asks 'how do I get more credits'. It also sets a hard boundary ('no in-MCP purchase flow; Stripe checkout requires a browser'), leaving nothing 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the account prerequisite and the scope of what a watch includes (pricing, jobs, news, plan-dependent signals). It stops short of describing pagination or return shape.

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 action and followed by the coverage scope and prerequisite. No filler, though the third sentence is a small afterthought rather than tightly integrated.

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

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

With no parameters, no output schema, and full annotation coverage, the description supplies the missing behavioral context (account requirement, signal scope) an agent would need. Only a hint about the returned list structure is absent, which is minor.

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 there is nothing for the description to disambiguate; baseline is 4. The description correctly implies no filtering arguments are needed.

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 ('List company watches on this API key') plus what each watch covers, so an agent can immediately tell this is a read operation. It does not explicitly name the create/cancel siblings, but the verb makes the distinction obvious enough.

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 implies when to use it (enumerating the watches tied to the current API key) and adds a prerequisite ('Needs a free StartupHub.ai account'). However, it never states when-not to use it or points at alternatives like create_monitor_watch or cancel_monitor_watch.

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 says the tool saves a listing unless preview: true is used and returns a listing id, which is a write/create operation. The annotations declare readOnlyHint: true, directly contradicting that 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?

The purpose and preview guidance are front-loaded, and the dense parenthetical lists efficiently pack the kind-specific URL semantics. It is slightly run-on, but for an 11-parameter tool most sentences carry 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 complex 11-parameter tool with no output schema, the description does well to state that it returns a listing id and that preview saves nothing. It still omits meaning for several parameters and, more seriously, does not resolve the readOnly contradiction with the annotations.

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 description adds useful meaning for kind, preview, price_per_call, and provider_key, including URL expectations and the 20% revenue share. However, with 11 parameters and only 36% schema description coverage, several parameters such as docs_url, price_unit, and free_calls_per_day remain undocumented in both the schema and 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 makes clear that this tool publishes/registers an API, MCP server, model endpoint, or A2A agent on the user's StartupHub profile so others can discover and pay for it. It is specific about the action and resource, but it does not explicitly differentiate itself from the similarly named sibling my_apis or from find_apis.

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 a concrete usage instruction: use preview: true first to validate without saving. It also explains the account/ownership prerequisite and maps each kind to the expected URL, but it does not explicitly name when to use my_apis or find_apis instead.

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?

With readOnlyHint/destructiveHint/openWorldHint already covering the safety profile, the description adds real value: it discloses the exact fields returned, that primary_email is gated by plan tier, and that a free account is required. It omits pagination/rate-limit behavior, but the added access and content context is substantive.

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, front-loaded with the return scope, then fields, then use cases and prerequisites. Each sentence carries information, though the field enumeration is slightly list-heavy.

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

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

No output schema exists, so listing the returned fields is valuable and largely covers the return shape. Plan-tier gating and the account requirement are also disclosed. Remaining minor gaps (pagination, slug format) keep it short of 5.

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 single 'slug' parameter is neither described in the schema nor clarified in the description ('for a startup' is too vague to tell an agent whether slug is a domain, name, or ID). The description fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Returns founders, current team, and board members for a startup, split by role') and even enumerates the returned fields. This clearly distinguishes it from siblings like get_startup (company record) or search_people (cross-company people search).

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 three concrete use cases (build org-charts, identify decision-makers for outreach, enrich a startup record), which conveys the intended context. It doesn't name an alternative tool or state when not to use it, but the usage 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 cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description adds genuinely useful operational context beyond them: the 100-domain cap, the 1 db credit charge only when matches are found, and the account requirement. It does not disclose failure modes or partial-match behavior, so it falls short of 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?

Front-loaded with the core action, then return fields, use case, limits, cost, and prerequisites in a logical order. Each sentence carries information, though the marketing-tinged framing ("funding intel", "cross-reference workflows") is slightly padded.

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 burden of describing return values and does so explicitly (match status, funding amount, latest round, investor IDs, sectors, founded date, HQ country). Combined with the limits, cost model, and auth requirement, 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?

With only one parameter and 100% schema description coverage, the schema already documents accepted domain formats and the 100 max. The description restates the same domain-array concept without adding format 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?

States a specific verb and resource: bulk-matching an array of advertiser/company domains against a startup database, and the description clearly distinguishes it from single-lookup siblings like get_startup_by_domain or get_investor_by_domain. The enumerated return fields make the operation 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 concrete, explicit use case ("what % of Google Ads / Taboola / Outbrain advertisers are VC-backed") that tells the agent exactly when this tool is the right choice over siblings. It stops short of naming exclusions, e.g. that single-domain lookups or other enrichment tools should be used instead.

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 readOnlyHint=true and destructiveHint=false, yet the description instructs the agent to pass remove_id to 'take one down' — an irreversible-looking mutation. That is a direct conflict with the declared safety profile, so the description actively misleads rather than adding trustworthy behavioral context. It also omits rate limits or what recheck actually does server-side.

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 compact clauses with the inventory description front-loaded, then the two parameter behaviors, then the account prerequisite. Every sentence carries information, though the opening sentence is slightly awkward in construction.

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 auth prerequisite (free StartupHub.ai account) and both optional parameters are covered, and there is no output schema so return-shape explanation is less critical. However, with a destructive-sounding remove operation and zero annotation coherence, the description should clarify what removal actually means and what recheck returns.

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%, so the description must carry the parameter burden, and it largely does: recheck_id is tied to re-reading a listing from its URL after spec/tool/agent-card changes, and remove_id to removal. The remaining gap is the expected ID/URL format, which is never specified.

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 and scope: the caller's own API directory listings, with call counts and earnings for the current month, plus the profiles they can be listed on. The verb is implied (a listing/read) rather than stated, and it never distinguishes itself from the obvious sibling list_my_api, so it falls short of a 5.

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 condition-based guidance for its two optional parameters (use recheck_id after changing spec/tools/agent card; use remove_id to take a listing down), which is genuinely useful. But it says nothing about when to choose this tool over find_apis or the near-identical list_my_api, so the core routing decision 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 a non-read-only, destructive operation, and the description adds meaningful behavior beyond that: public link exposure, embed URLs, account requirement, and the SEO caveat. It does not fully explain side effects such as whether existing embeds break on unpublish, but it is substantially more informative than the annotations alone.

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-loads the main action and inverse action. Every sentence contributes useful information about outputs, account requirements, or SEO behavior.

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

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

For a two-parameter publishing toggle with no output schema, the description is complete enough: it explains the public/private outcomes, mentions the resulting public and embed URLs, and notes the account requirement and SEO limitation.

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 parameters are already documented in the input schema. The description reinforces the `publish` boolean semantics but adds little beyond the schema, so the baseline score 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 gives a specific verb and resource: publish a market map, and clearly covers the inverse action of making it private again. It also distinguishes the public-link/embed outcome from related map operations such as creating or editing.

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 how to use the tool in both directions: publish with `publish: true` or make private with `publish: false`. It gives useful context such as being free, requiring an account, and not automatically placing the page in search engines, though it does not name sibling 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 establish the safe-mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely new context: authentication via Application Password, the external StartupHub account requirement, and that 'publish' goes live immediately — useful side-effect disclosure beyond 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?

Five short sentences, purpose first, with the prerequisite and default trailing. Efficient, but the status enumeration in the description duplicates the schema's own enum/default documentation, which is mildly redundant.

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 ten-parameter content-creation tool with no output schema, the description omits what the call returns (post ID, URL, or failure modes), which is the main missing piece an agent would need. Auth, credentials, and default status are covered adequately.

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 schema already documents all ten parameters in detail, including enum values, defaults, and format hints. The description only restates the status enum and default, adding no meaning the schema lacks; baseline 3 applies.

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

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

States a specific verb and resource: 'Publish HTML to a WordPress site' and 'Creates a post with the given title and HTML body'. No sibling tool targets WordPress, so it is functionally distinguishable, though it never explicitly contrasts itself with the submit_* family that also creates published content.

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 surfaces the account prerequisite ('Needs a free StartupHub.ai account') and the three status values with the default, which implies usage context. However there is no guidance on when to prefer this over other content submissions or what preconditions (validated credentials, existing site) must hold.

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?

Goes well beyond the read-only annotations by disclosing no-API-key/free access, the exact return payload (count, total USD, chart URL, periods/categories), and non-obvious edge behavior: that dataset=startups dollars are raised-to-date rather than in-year, that group=sector double-counts and inflates totals, and that split keeps the total de-duplicated.

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?

Long but dense and front-loaded: the core capability and example come first, then per-dataset semantics, then return shape. Nearly every sentence carries decision-relevant information (dataset selection, grouping caveats, return format) rather than 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?

For a 12-parameter aggregate tool with no output schema, it explains return values itself and covers the semantic traps (dataset differences, sector double-counting, split de-duplication, invalid-value fallbacks) that an agent must understand to call it correctly. Nothing essential is left to inference.

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 baseline is 3, but the description adds genuine interpretation beyond the schema: what the dollar total means per dataset, the higher total implied by sector grouping, and the annual/series scoping caveats. It does not restate most param mechanics, which the schema already covers.

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 capability (aggregate funding/rounds/founded-company counts by country, sector, series, year) with a concrete verb-resource framing and the anchor 'the StartupHub /analysis chart as data'. This clearly distinguishes it from per-entity siblings like get_company_funding and get_startup_funding_history, which return individual records rather than aggregate totals.

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 usage context with a worked example question ('how much funding did Canadian startups raise in 2026') and explains which dataset to pick for which question type. It lacks an explicit when-not statement or a direct pointer to the per-company funding siblings, so it stops short of full routing 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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds meaningful context beyond that: ratings are aggregated anonymously in a public monthly report and never surfaced as customer reviews, which tells the agent the data's downstream use. It doesn't describe the response, but this is a small submission tool.

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 compact sentences, front-loaded with 'Optional' and the core action, with privacy and cost details after. Every clause carries 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 simple three-parameter submission tool with no output schema and safe annotations, the description covers purpose, cost, and data handling. Only a hint about what happens on success or invalid input is missing, which is minor.

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 schema already documents score, reason, and would_pay. The description adds the 1-5 range (already in schema) and 'short reason' emphasis but no new 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?

States a specific verb and resource ('Rate how well StartupHub.ai served this task') with an explicit 1-5 scale, so the action is unambiguous. It does not name or contrast with siblings like check_domain_rating, but those are clearly ratings of other entities rather than of the service itself.

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?

'Optional' sets the when-to-use expectation, and 'Free, no API key' removes the main reason an agent might hesitate. It lacks an explicit when-not condition (e.g., only after completing a task), 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses three traits an agent otherwise could not know: the tool is asynchronous and returns a job id, it requires an API key and a free StartupHub.ai account, and it consumes clip credits. Cost and auth disclosure on a non-destructive write tool is exactly the context annotations cannot supply.

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?

Six short sentences, each earning its place: purpose, required inputs and their source, return value, follow-up call, cost, and auth prerequisite. Purpose is front-loaded in the opening sentence.

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, and the description responsibly explains the async job-id return and the polling step. Combined with auth and cost notes, an agent has enough to invoke and follow through correctly; only the semantics of the optional styling parameters remain uncovered.

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 38%, so the description is expected to compensate. It names video_url, start_seconds, end_seconds, and quote and notes quote's origin, but leaves hook, style, aspect, and video_id entirely unexplained in both schema and description, so the compensation is partial.

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

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

States a specific verb (render) and resource (one YouTube clip), and the workflow sentences make clear it is distinct from get_youtube_clip (the polling tool) and suggest_youtube_clips (the source of parameters). It does not, however, explicitly distinguish itself from the other video-generation sibling, generate_article_video.

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 clear operational context: pull video_url, start_seconds, end_seconds, and quote from suggest_youtube_clips, then poll get_youtube_clip until status is done. The when-to-use path is spelled out, but there are no exclusions (e.g., when not to render, how to pick start/end).

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 genuinely useful behavior (cost billed to credits, failed attempts refunded, sequential fallback up to the fallback limit), but it directly conflicts with the structured annotations: a tool that executes real tasks, spends credits, and whose own example label is "book the reservation" is declared readOnlyHint=true and destructiveHint=false. That is an annotation contradiction under the scoring rules.

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

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

Front-loaded with the core mechanic, then billing, then long-task handling, then dry_run and the prerequisite. Every sentence carries information; it is slightly dense but not padded.

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 supplies the key return semantics (route_id, refunds on failure, pay only for the completing agent) and the follow-up tool. It does not describe what the successful task result itself looks like, which is the main remaining gap for a 7-parameter executor.

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 71%, and the description still adds meaning the schema lacks: dry_run is defined as showing the ranking without executing anything, and route_id is explained as the handle for get_api_task. fallbacks and prefer remain defined only by the schema/enum, but the description carries the semantically ambiguous 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?

"Give a task and StartupHub picks the agent to run it" names a specific action and resource, and the ranking/fallback explanation makes clear this is a router/executor rather than a direct API caller like call_api. An agent can distinguish it from find_apis (discovery) and get_api_task (retrieval) 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?

It gives concrete selection context: use dry_run to see the ranking without running, use get_api_task with the returned route_id for long tasks, and a free account is required. It does not explicitly contrast with call_api for cases where you already know which API to call, so the when-not guidance is incomplete.

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 the safety profile (readOnly, non-destructive, open world), and the description adds value beyond them: no credits charged ('Free'), the scoring output shape, the disputed 8-point bonus rule and its optionality, and the fix-prompt artifact. These are operational facts an agent cannot derive from 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?

Front-loaded with purpose, output, and cost before the workflow guidance, and every sentence carries distinct information (scoring rules, bonus caveat, outreach workflow, self-audit). The outreach-workflow sentence is long and could be tightened, but nothing is truly redundant.

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 only one parameter, the description carries the return-value burden and does so explicitly (0-100 score plus per-check pass/fail plus fix prompt). Combined with the cost note and the bonus caveat, an agent has everything needed to call this 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 single url parameter already has an example in the schema, so the description is not required to explain parameters. It adds no syntax, format, or constraint detail beyond what the schema provides, 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 ('scans') + resource ('a public site') + the exact standard being evaluated (AI-agent readiness, llms.txt v2 shape). It also names the concrete artifact produced (0-100 score with per-check pass/fail), which separates it cleanly from siblings like discover_email or get_trends.

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 describes a common workflow (search the web, scan each site, then call discover_email on the lowest-scoring ones) and names the exact selection condition (lowest score = outreach hook). It also gives a second use case (self-audit of the user's own sites), so both when-to-use paths are 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?

Goes well beyond the readOnlyHint/destructiveHint annotations by disclosing billing ('Costs 1 credit'), an auth prerequisite ('Needs a free StartupHub.ai account'), and caching semantics (stored fingerprint vs. live read). Missing only failure modes or rate-limit 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?

Five short sentences, front-loaded with the identity line, then output, then the caching rule, then cost and account requirement. 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?

For a read-only scan with no output schema, the description adequately covers the returned categories, cost, and auth requirement. It leaves the exact response shape unspecified, but nothing needed to invoke the tool correctly is absent.

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 parameters are already documented in the schema. The description adds mild reinforcement ('Accepts a URL or a plain domain') but no syntax or format detail beyond what the schema already provides, matching the baseline 3.

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 ('Return hosting, frameworks, analytics, payments, and mail setup for a company website') with the returned categories enumerated. No sibling tool covers tech-stack detection, so it is unambiguously distinguishable from scan_agent_readiness or check_site_speed.

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?

Explains the caching decision rule precisely: a stored fingerprint is checked first, and a fresh live read happens when live=true. It does not name alternatives or exclusions, but no sibling overlaps, so context is sufficient without them.

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, and non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: per-video billing, no charge on failures, per-call limits (15 feed / 100 full), and a free-account requirement. Rich, but annotations carry much of the load.

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, leading with purpose and mode behavior before pricing details. Every sentence carries information, though the pricing and billing sentences add length an agent may not always need. 5,

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 proactively lists return fields for each mode, and covers mode behavior, limits, billing, auth requirements, and endpoint equivalence. Nothing needed to invoke correctly appears to be 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%, so the baseline is 3, but the description goes further by explaining what each mode returns (feed fields vs the full watch-page field set) and the per-mode limit ranges, adding meaning beyond the 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 (video metadata for YouTube channels and video URLs) and immediately scopes it against siblings with 'no transcripts,' routing agents away from get_youtube_transcript. The feed vs full mode split makes the exact retrieval behavior 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 explicit mode-selection conditions: 'feed' (default) for latest uploads and cheap pricing, 'full' for every watch-page field and deeper history, plus the rule that video URLs always return full rows. Combined with the 'no transcripts' exclusion, an agent can choose this tool and its mode without inference.

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