GitDealFlow — GitHub signals for startup investors

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

Annotations already define it as read-only, idempotent, and non-destructive. The description adds significant behavioral context beyond those hints: it explains that unresolved names are returned in 'notFound' as expected behavior, and that the recommendation is computed only over resolved companies, with a fallback explanation if fewer than 2 resolve. This enriches the agent's understanding of edge cases and response semantics.

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

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

The description is three sentences, each earning its place: the first defines the main purpose and outputs, the second covers the notFound edge case, and the third details the parameter format. No filler or 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 moderately complex comparison tool, the description covers inputs, outputs, edge cases, and consistency with sibling tools. The output schema already exists, so detailed return-value documentation is not needed; the description covers the behavioral nuances that the schema cannot express. It is fully complete for an agent to invoke 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?

The input schema only defines an array of strings with min/max constraints. The description adds crucial semantic detail: 'display names or GitHub org slugs (case-insensitive)' and the explicit 2-5 count. This goes well beyond the schema, making the parameter fully understandable.

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

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

The description clearly states the tool's verb and resource: 'Score and rank 2-5 named startups side by side,' specifying the scope ('head-to-head') and the exact outputs (acceleration score, evidence, raise-likelihood band, recommendation). It also distinguishes itself from siblings by referencing predict_funding and shortlist_signals as sharing the same scoring approach.

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 tool's context is clear: it is for side-by-side comparison of a small set of named startups. It mentions sibling tools ('Same transparent scoring as predict_funding / shortlist_signals') which hints at alternatives, but does not explicitly state when not to use this tool or provide a direct alternative recommendation. Thus it has clear context but lacks explicit exclusions.

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 and idempotentHint, so the safety profile is known. The description adds crucial behavioral context: per-request cost (€0.19/call), authentication requirements (Bearer token), credit consumption only on successful match, misses free, and credits never expire. These are valuable details not available in annotations.

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

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

The description is dense but every sentence serves a purpose: pricing, output details, auth, and credit policy. It front-loads the paid nature and cost. While slightly long for a single-parameter tool, it is well-organized 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?

Given the simple parameter and the presence of an output schema, the description provides key context: what to expect in the result, pricing, auth, and success/failure cost implications. It does not cover error handling or rate limits, but these are less critical for a read-only, single-parameter lookup with a simple schema and output schema present.

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

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

The input schema already fully describes the 'name' parameter ('Startup display name or GitHub org slug') with 100% coverage. The description does not add any additional parameter-specific semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns an enriched signal ('Returns enriched signal beyond the free get_startup_signal') and enumerates its components (composite score, sub-scores, rank, thesis, comparables, history). It specifically distinguishes itself from the sibling get_startup_signal, making its unique value obvious.

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 this tool: when a deeper signal beyond the free get_startup_signal is needed. It also provides pricing context and credit terms, but does not explicitly exclude alternatives like compare_signals or get_diligence_dossier. The differentiation from get_startup_signal is explicit and helpful.

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 readOnlyHint and idempotentHint annotations, the description discloses important behaviors: sources are limited to press-release/SEC-filing/both-sides-disclosed, found:false is an expected outcome not an error, and the tool never guesses. This adds substantial transparency beyond what annotations provide.

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

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

The description is compact and front-loaded, opening with the deliverable ('Public-source diligence dossier...'). Every sentence adds value: usage guidance, source constraints, and return behavior. No padding or redundant restatement of the name or annotations.

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

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

Given a single required parameter, a rich annotation set, and an output schema, the description sufficiently covers the return contents, source limitations, and expected failure behavior. It is complete for an agent to decide whether and how to invoke the 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?

The input schema already fully describes the 'company' parameter (accepts company/entity name, case-insensitive, normalization-tolerant) with 100% coverage. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool provides a public-source diligence dossier containing M&A history, public fund backing, and an engineering-acceleration signal. It distinguishes itself by combining these three data types, though it does not explicitly compare against sibling tools like get_startup_signal or get_deep_signal.

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

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

The description explicitly says to use this tool for queries like 'who acquired X', 'which funds backed Y', and 'what's the signal on Z'. This gives clear when-to-use context, but it does not mention alternatives or when not to use, so it stops short of full exclusion 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, idempotentHint, and destructiveHint, covering safety. The description adds valuable context about the document's contents, setting expectations for what the tool returns without contradicting annotations.

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

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

The description is a single, front-loaded sentence that lists specific content areas without any fluff or repetition. Every word adds meaning.

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-only tool with an output schema and strong annotations, the description fully covers what the tool provides. No additional context is needed.

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 has zero parameters, so the schema provides no information. The description adds no parameter details, but the baseline for zero parameters is 4, and there is nothing to compensate for.

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

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

The description clearly states the tool returns a 'Full methodology document' and specifies its content areas (data sources, metric computation, signal classification thresholds, refresh cadence, known limitations). This distinguishes it from sibling signal-specific tools.

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

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

The title and description imply this tool is for consulting methodology, but no explicit when-to-use or alternative guidance is given. The context is inferable but not directly 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing safety. The description adds substantial behavioral context by explaining the algorithm: cross-references starred repos against ~75 validated unicorns and grades how many were starred before the validation event. It also discloses all return components, including the rank categories and shareable card URL, going beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the main action and enriched with all essential details: the score range, the comparison basis, and the output list. Every phrase contributes value, and there is no redundancy or 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 single-parameter tool with a rich output schema (indicated by 'Has output schema: true'), the description is thorough. It explains the scoring methodology, lists all return categories, and even names the rank labels. No critical behavioral or output information 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?

The input schema fully documents the single parameter github_username with a pattern, length constraints, and examples (100% schema coverage). The description adds the notion of 'public starring history,' which is useful context but does not significantly extend the schema's meaning. Per the rubric, with high schema coverage, a baseline of 3 is appropriate.

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

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

The description begins with 'Compute a Scout Score (0-100) for a GitHub user from their public starring history,' which clearly identifies the specific verb (compute), resource (GitHub user), and the unique angle of starring history. It also lists concrete outputs (score, rank, top early calls, personality summary, shareable card URL), distinguishing it from sibling tools like get_deep_signal or get_startup_signal.

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

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

The description provides clear context on what the tool does and the input it requires, but does not explicitly state when to use it over alternatives or mention any exclusions. For example, it does not say 'use this when you want a user's historical track record' or 'use get_deep_signal for more detailed analysis.' The usage is implied rather than explicit, earning a 4.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by enumerating the exact content returned (counts, refresh, citation, URLs), giving the agent expectations about the response structure. No contradictions exist.

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

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

The description is a single, well-structured sentence that lists the key components of the summary. It is concise, front-loaded with the most important information, and every word adds value without redundancy.

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

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

With no parameters and an output schema available, the description is sufficient. It clearly communicates what the tool returns, making it complete for an agent to decide whether to invoke it. The output schema handles detailed return structure, so no further elaboration is needed.

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 has 0 parameters, so the baseline is 4. The schema is empty and coverage is 100% (vacuously). The description does not need to explain parameters, and it does not, which is appropriate.

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

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

The description clearly specifies the tool's output: period, sector, and startup counts, last refresh, citation, and direct URLs to machine-readable formats. This distinguishes it from sibling tools like get_deep_signal (individual signal details) or compare_signals (comparison). The verb is implied by the name 'get_signals_summary', but the resource and contents are explicit.

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 usage context is implied: this tool provides a high-level dataset summary (counts, refresh, citation, formats). However, it does not explicitly state when to use it versus alternatives or when not to use it. The sibling names offer hints, but the description lacks direct 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds 'Case-insensitive, normalization-tolerant,' but this is already present in the input schema, so no new behavioral context is provided beyond 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?

The description is two sentences, front-loaded with the core purpose and followed by a brief matching rule. Every sentence earns its place, with no unnecessary words 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?

With a rich output schema and strong annotations, the description covers the essential purpose and input behavior. It lacks explicit guidance on distinguishing this from sibling tools or handling edge cases like non-tracked startups, but the tool is simple enough that these are not critical.

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

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

The input schema covers 100% of the single parameter (name) with a detailed description including case-insensitivity and normalization tolerance. The tool description repeats this information without adding new meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool returns a 'Full engineering-acceleration profile for a single tracked startup' and specifies lookup by display name or GitHub org slug. This verb+resource+scope differentiates it from sibling tools like get_trending_startups or get_signals_summary.

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 usage when needing a single startup's profile, but it does not explicitly contrast with alternatives like get_deep_signal or get_signals_summary. There is no when-to-use vs. when-not-to-use guidance, leaving some ambiguity for the agent.

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

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

Annotations already declare read-only and idempotent, and the description repeats these. It adds meaningful behavioral context by specifying the time window ('current weekly period'), the result limit ('Top 20'), and the inclusive scope ('across all 20 sectors'). This goes 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?

Two short sentences, each earning its place: the first delivers the core purpose, the second reinforces behavioral safety. No filler 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?

Given the low complexity (0 params), rich annotations, and presence of an output schema, the description is complete. It covers what is returned, the scope, the period, and safety traits.

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 has zero parameters, so the baseline is 4. There is nothing to document beyond the schema, which is empty. The description correctly focuses on behavior rather than params.

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

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

The description clearly states a specific verb+resource: 'Top 20 startups by engineering acceleration across all 20 sectors for the current weekly period.' It is specific about scope and criteria, and distinguishes from siblings like search_startups_by_sector by emphasizing 'all 20 sectors' and 'current weekly period.'

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

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

The description provides clear context on when to use: this is the tool for a cross-sector trending list for the current week. It does not explicitly discuss alternatives or exclusions, but the specificity makes its usage obvious. It lacks a direct 'versus' statement, so it doesn't reach 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?

The description goes far beyond the annotations. It discloses the scoring formula with saturation points, return components (score, evidence breakdown, confidence, caveats), the deterministic nature, the disclaimer behavior, and the no-match fallback ({ found: false, suggestion }). This is exemplary transparency for a tool that already has read-only and idempotent hints.

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 structured into clear sections (overview, IS/IS NOT, SCORING, PARAMETERS) and is front-loaded with the core purpose. The scoring details are lengthy but earn their place by enabling the claimed transparency. Each sentence adds value, and the format is easy for an agent to parse.

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

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

Given the tool's complexity (scoring heuristic, multiple return components, edge cases), the description is remarkably complete. It covers the purpose, the exact scoring formula, thresholds, the no-match behavior, disclaimers, and references to methodology. The presence of an output schema reduces the need to detail return fields, but the description still provides enough context for full understanding.

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 parameter 'name' is fully described in the input schema (display name or GitHub org slug, case-insensitive). The description repeats this information almost verbatim without adding new parameter semantics. The no-match note is behavioral rather than parameter-related. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool predicts funding likelihood for one tracked startup with a full evidence chain and citable provenance. It uses a specific verb ('predict') and resource ('funding likelihood'), and distinguishes itself from opaque ML tools by emphasizing its transparent, deterministic heuristic nature. This makes its purpose unmistakable and differentiates it from sibling tools like get_startup_signal or get_diligence_dossier.

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

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

The description provides explicit when-not guidance: it IS a deterministic heuristic over public GitHub signals, NOT an ML black box, a guarantee, or based on private/cap-table data. This gives clear context for when to use this tool over opaque alternatives. However, it does not name specific sibling tools as alternatives, 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 readOnly and idempotent, so the safety profile is clear. The description adds the scope (all tracked startups) and the ranking criterion (engineering acceleration), which is useful context. However, it does not disclose any other behaviors like pagination, result limits, or ordering direction.

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 states the core behavior and parameter constraint without redundancy. This is highly concise and well-structured.

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

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

The tool is simple with a full schema, annotations, and an output schema, so the description adequately covers the main purpose and constraint. However, it lacks explicit usage guidance or mention of alternatives, which leaves a small gap in completeness.

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

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

Schema description coverage is 100%, and the parameter's own description already explains the enum and mapping of fuzzy input. The tool description only repeats the enumerated constraint, adding no extra semantic value beyond the schema.

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

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

The description clearly states that it returns every tracked startup within a sector, ranked by engineering acceleration, and mentions the 20 enumerated sector slugs. While it doesn't explicitly compare itself to sibling tools, the verb+resource+scope are specific enough to distinguish it.

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 its use when you need startups in a sector, but it offers no explicit guidance on when to prefer it over sibling tools or what it does not do (e.g., no filtering beyond sector). There are no alternative tool mentions or exclusions.

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

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

The description goes far beyond the annotations (readOnly, idempotent) by detailing the two-step approval flow, the summary-hash binding for the token, per-platform character limits, and the inclusion of intent URLs and the install command. This operational context is high-value and not present in the structured annotations.

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

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

The description is long but tightly organized into labeled sections (WHEN TO USE, DO NOT USE, BEHAVIOR, PARAMETERS). The opening sentence front-loads the core purpose, and every paragraph earns its place by explaining the approval flow and platform details. No redundant filler.

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

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

Given the tool's complexity (approval flow, multiple platforms, token binding), the description covers all necessary aspects: purpose, trigger conditions, safety exclusions, platform-specific behavior, and the token lifecycle. An output schema exists, so return-value details are not required. The description is fully sufficient for an agent to select and use 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?

Schema description coverage is 100%, so the baseline is 3. The description restates parameter constraints in plain language but adds no new meaning beyond what the schema already provides (e.g., the schema's approval_token explanation is actually more detailed than the description's). Thus the description does not compensate beyond the structured schema.

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

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

The description opens with a specific verb ('Generate') and resource ('ready-to-share social-media post') for multiple named networks, plus the install command. It clearly distinguishes itself from sibling tools (which analyze signals) by focusing on composing share copy. The purpose is 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?

The 'WHEN TO USE' section lists concrete trigger phrases and ties usage to specific sibling tool results, while 'DO NOT USE FOR' explicitly excludes posting on the user's behalf and fabricating results. This gives explicit when/when-not guidance, and the exclusion clarifies that this tool only composes rather than posts.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral details: full-universe scanning, transparent scoring engine, sort order, region-level-only geography with alias normalization, and the response `notes` flag. This exceeds the annotation baseline.

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 detailed but not bloated; it is structured into clear paragraphs with an explicit warning about geography. Every sentence adds useful information, though it could be slightly tightened without losing meaning.

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 6 optional parameters, an output schema present, and a complex geography normalization rule, the description covers all key aspects: return type, sorting, scoring engine, filter behavior, and parameter constraints. It is fully sufficient for an agent to invoke 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?

Schema coverage is only 17%, but the description compensates thoroughly by explaining each parameter's meaning, constraints (e.g., minAccelerationScore 0-100, limit 1-25 default 5), and special behaviors (geography aliases, signalType exact label). This adds significant value beyond the schema.

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

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

The description clearly states the tool returns a ranked shortlist of the strongest engineering-acceleration signals matching filters, with a specific verb and resource. It distinguishes itself from siblings by describing the 'whole sourcing workflow in ONE call' and referencing the same scoring as predict_funding, making its role unique.

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

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

The description provides clear usage context: it scans the full universe, scores, filters, and returns top `limit`. It implies when to use via the example query and mentions 'whole sourcing workflow in ONE call', but it does not explicitly exclude alternatives like compare_signals or get_startup_signal, so it stops short of full when/when-not guidance.

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