Fodda Topic & Trend Research

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining polling behavior and expected status outcomes, which is not covered by annotations.

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

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

Two sentences are concise and front-loaded with purpose, then usage instructions. No unnecessary words.

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

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

Despite no output schema, description explains return status meanings. With one required parameter and clear usage context, the description is fully adequate.

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 'job_id' with description in schema. Schema coverage is 100%, so description adds minimal extra meaning. Baseline score of 3 is appropriate.

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

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

Description clearly states the tool checks completeness of market data gathering and retrieves results, using specific verb 'check' and resource 'supplemental status'. It also distinguishes from sibling tool get_supplemental_context by stating to call after 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?

Explicitly specifies when to use the tool: after get_supplemental_context, with polling interval of 5-10 seconds until COMPLETE or FAILED. No explicit exclusions or alternatives, but 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=true, idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: the return format ('Returns a branded SVG that renders directly in the chat') and the focus-highlighting mechanism. Generating an in-chat artifact with no side effects is consistent with the readOnly/idempotent annotations, so there is no contradiction.

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 that each earn their place: core purpose, chart-type options, then output behavior and the focus feature. The chart-type enumeration is long but necessary for correct invocation, and the most important information is front-loaded.

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

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

For a tool with no output schema, the description compensates by stating precisely what is returned (a branded SVG that renders in chat). The per-chart data shapes in the schema plus the chart-type semantics in the description cover all call paths, though error conditions and data-size limits are not addressed — a minor gap for a 2-parameter generation 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 is 3, but the description genuinely elevates it by decoding each chart_type enum value ('implication_ladder' = Signal→Trend→So What→Do What, 'opportunity_map' = 2×2 white space analysis), which helps an agent select the correct variant. It also front-loads the focus parameter behavior that the schema buries inside a JSON-string description.

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

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

The description opens with a specific verb+resource pair ('Create a presentation-ready data visualization from research findings') and then enumerates six concrete chart types with their conceptual shapes (e.g., 'cultural_shifts' = From→To transitions). This unambiguously distinguishes it from the sibling tools, which are all get/search/list/read operations, so an agent can tell this is the generation tool 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?

The purpose statement implies the clear usage context — when a visual artifact is needed rather than raw data — and the chart-type list guides which configuration to pick. However, the description never explicitly states when to prefer this over alternatives or what conditions rule it out, 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns with usage instructions, which is helpful context but does not substantially go beyond what annotations and the overall intent reveal.

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 concise at two sentences, front-loads the core action, and avoids redundant restatement of the tool name. The slash-separated list is somewhat verbose but helps capture the breadth without adding real bloat.

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, optional-parameter tool with no output schema, the description provides enough guidance on when to call it and what it returns. It could mention the return format or the role of userId, but the existing context is sufficient for an agent to decide and execute.

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 userId fully described as 'Optional user identifier.' The description does not explain why or how userId should be used, but the schema handles the parameter 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 states a specific verb ('Returns'), a clear resource ('Fodda's main capabilities / features / offerings / products / services / tools'), and adds the purpose 'and how to use them.' This makes the tool's function immediately identifiable and distinguishes it from sibling data-retrieval tools like get_node or search_graph.

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

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

The description gives explicit guidance: 'Call this for any question about what Fodda can do or what's available.' This is a clear when-to-use directive, though it does not explicitly state when not to use it or point to alternatives.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds concrete behavior beyond that by detailing what each returned evidence item contains, including source URL, brand names, publication date, and formatted citation. Since there is no output schema, this compensates well.

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: what it does, what it returns, and when/how to use it. No fluff, and the critical usage constraint is clearly placed near the end for emphasis.

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 no output schema, the description adequately covers the return values by listing the item fields. Required parameters are fully documented in the schema, annotations handle safety and idempotency, and usage context references search_graph appropriately. Nothing critical is missing for the agent to invoke this 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 100%, so the schema already explains graphId, for_node_id, top_k, and userId. The description adds the useful framing that this is 'a direct lookup by trend ID,' but it does not materially extend the parameter semantics already documented in the schema.

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

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

The description clearly states the tool retrieves source articles, case studies, and statistics for a specific trend, with citations and publisher attribution. It also explicitly distinguishes itself from a text search tool, making its direct-lookup-by-ID role 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?

It provides clear when-to-use guidance ('Use after search_graph when you need the supporting proof behind a trend') and excludes text-search usage. It does not enumerate all sibling alternatives or contrast against search_insights/search_statistics, but the context is strong enough for an agent to select it correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: that label='Trend' returns a 'full deterministic list' and that search may return partial results, which implies a completeness guarantee beyond what annotations express. The openWorldHint=false also aligns with the deterministic-list claim, so no contradiction 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?

Three sentences with no filler: the purpose, usage guidance, and exception case are each in their own sentence. The most important usage guidance (when to call with label='Trend') is front-loaded. It's slightly wordy with examples, but the examples earn their place by illustrating the query patterns 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 read-only list tool with fully-documented parameters (100% schema coverage) and no output schema, the description covers the main use case, the special deterministic case, and clearly distinguishes from search_graph. Minor gap: it doesn't explain the 'property' parameter's behavior beyond 'defaults vary by label,' but the schema covers this, and the complexity is moderate. An agent can call this 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 100%, so the baseline is 3. The description reinforces the label parameter semantics by naming the label values ('Brand', 'Location', 'Technology', 'Audience', 'RetailerType', 'Trend') and clarifying the special behavior of 'Trend'. It doesn't add new parameter semantics beyond the schema, but it doesn't need to — the schema descriptions are comprehensive.

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 ('List') with a clear resource ('brands, locations, technologies, audiences, or trends within a specific knowledge graph') and provides concrete example queries. It also distinguishes itself from search_graph ('To get a complete list of every trend in a graph... useful... where search may return partial results'), which differentiates it from sibling tools. This is a clear, specific purpose statement.

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 exploring graph contents and contrasts it with search_graph when full deterministic lists are needed ('useful for industry-report graphs where search may return partial results'). This gives the agent explicit when-to-use and when-not-to-use guidance, naming the alternative tool.

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, destructiveHint=false. The description adds value by noting 'Returns live data — not cached from session start', informing the agent of data freshness. No contradictions.

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: first states purpose, second gives usage examples and data freshness note. No unnecessary words, front-loaded structure.

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?

Complexity is low (0 parameters). Annotations cover safety, description lists return values (balance, plan, graphs, profile). Output schema is absent but the description sufficiently enumerates response fields.

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

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

No parameters exist, so schema coverage is 100% trivially. Per guidelines, 0 parameters yields baseline 4. No need for additional parameter info.

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 ('Check') and resource ('current user's account status'), enumerating exact contents (API call balance, plan, graphs, profile info). It clearly distinguishes from sibling tools like 'check_supplemental_status' and 'get_capabilities'.

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 lists example user queries ('how many API calls do I have?', 'what plan am I on?') that trigger use. While it does not mention when not to use, the guidance is clear and actionable.

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 agent knows it is a safe read operation. The description adds value by revealing that results are 'curated editorial connections' that are not raw graph data, and expresses the important behavioral constraint that node_id must come from a prior search_graph result. No contradictions found.

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

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

The description is compact and front-loaded with the core action, then adds usage instructions and a prerequisite. It is efficient, although there is minor redundancy between 'that search alone wouldn't surface' and 'that web search cannot provide', so it earns just under a 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?

For a graph traversal tool with seven parameters, the description is contextually sufficient: it names the workflow (search_graph first), the situations in which to use it, and the general nature of the return value. There is no output schema, but the description does not need to list every return field; it provides enough to understand the tool's purpose and correct call sequence.

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 is already documented in detail: graphId examples, depth defaults, limit, direction enum, seed_node_ids requirement, and relationship_types enum. The description only echoes the node_id prerequisite already present in the schema. It adds no unique parameter-level meaning, so the baseline 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 starts with a specific verb and resource: 'Discover what's connected to a specific trend' — related brands, technologies, locations, and cross-domain links. It also explicitly distinguishes itself from plain search by saying 'search alone wouldn't surface' and returns 'curated editorial connections that web search cannot provide', making it clearly different from siblings like search_graph or get_node.

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

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

The description gives explicit usage context: 'Use after search_graph' and describes the use cases: map the territory around a trend, find connected brands, or understand cross-domain relationships. It also states the prerequisite: 'Requires node_id from a prior search_graph result.' It does not explicitly list when-not-to-use or name an alternative delta, but the use-after-search_graph guideline 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 communicate read-only, idempotent, non-destructive behavior. The description adds useful context by listing what the response contains (lifecycle stage, signal strength, geographic scope, all properties) and by highlighting the external dependency on a previously obtained node_id. This goes beyond the structured annotations without contradicting them.

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

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

The description is a compact three-sentence structure that front-loads the core purpose and return content, then provides the usage condition and dependency. No wasted words or repeated schema details.

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 node retrieval with no output schema, the description adequately explains the return categories and the required prior context. It does not cover failure or edge-case behavior, but the schema handles node_id constraints well, so an agent has enough information to call 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% and the schema itself provides detailed parameter guidance, including strong warnings against guessing node IDs and example graph IDs. The description mostly restates the node_id dependency already present in the schema, so it adds little new 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?

Clearly specifies a single verb ('Get'), a resource (a specific trend/node), and the type of payload returned: full profile including description, lifecycle stage, signal strength, geographic scope, and all properties. It also frames itself as a deeper follow-up to search_graph, which distinguishes it from the main sibling likely to be confused with 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?

Tells the agent when to use it ('when you need deeper detail on a single trend after search_graph returned a summary') and states a required precondition: node_id must come from a prior search_graph result. It could be stronger by explicitly naming related alternatives like get_neighbors or get_evidence and saying when not to use 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 handle readOnlyHint and destructiveHint, but the description adds useful behavioral context: the call fans out to 80+ sources in parallel and returns 'categorized data blocks with source attribution and metadata.' It clarifies that the tool is an aggregator of third-party data sets, not merely a local read query. No contradiction exists with the read-only annotation.

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 substantial — five sentences — but each sentence earns its place: layer definition, call condition, source list, return format, and sequencing with search_graph. It is structured and readable, though slightly denser than necessary.

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?

Without an output schema, the description covers the essential expectation: 'Returns categorized data blocks with source attribution and metadata.' It also connects to search_graph's annotations and lists example sources. It does not spell out possible error cases or pagination, but for a read-only data-returning tool this is sufficient for first-line usage.

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 schema description coverage is 100%, so the baseline is 3; the description's main parameter guidance is implicit through scenarios like 'demand/attention-shaped queries.' It does not add parameter-level meaning beyond the schema, but because the schema is thorough, the definition still supports correct invocation.

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 purpose with concrete nouns: 'macro, institutional, and real-time market data' and enumerates source examples (Google Trends, FRED, BLS, Census). It also distinguishes the tool from the sibling search_graph by explicitly framing it as the call after search_graph reports thin/empty coverage.

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

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

The description gives explicit decision criteria: 'Use this tool when curated coverage is thin, empty, or when the query is explicitly demand/attention-shaped.' It also provides the fuller execution context — call after search_graph sends back a thin/empty coverage annotation — so an agent can determine when to invoke this tool over 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 cover the safety profile: readOnlyHint, idempotentHint, and destructiveHint are all aligned. The description adds meaningful behavioral context beyond those annotations by clarifying that results are cross-validated by Fodda's pipeline and that they connect analyst/CEO statements with consumer trend signals. It does not detail return structure or pagination, but the schema already documents the limit parameter and the annotations lower the burden.

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

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

The description is two sentences with no filler: the first states what the tool returns, and the second explains the analytic connection that gives the output its meaning. It avoids repeating the title or restating schema fields, and 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?

For a read-only, optional-parameter lookup with a fully documented schema and no output schema, this description supplies the key missing context: the domain (earnings reports), the validation process, and the analytic link between executive commentary and consumer trends. It could additionally describe the shape of a trend result or list exclusion criteria, but those gaps are minor given the overall simplicity of 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?

Schema description coverage is 100%, so the baseline is 3; all five parameters already have explicit descriptions. The tool description adds general context around earnings reports and validated trends, which makes the search/sector/ticker filters feel coherent, but it does not add any parameter-specific semantics beyond what the schema already provides.

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

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

The description uses a specific verb ('Returns') and names a distinct resource: market-validated consumer trends from corporate earnings reports, cross-validated by Fodda's analysis pipeline. It also clarifies the analytic output by connecting earnings commentary with consumer trend signals. It does not explicitly contrast with sibling tools like search_insights or get_evidence, but the 'validated trends' framing is specific enough to differentiate 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 intended use is implied: call this tool when you want pre-validated consumer trends derived from earnings-report commentary rather than raw evidence or general graph search. However, it never explicitly states when not to use it or names alternative tools, so an agent must infer the routing from the 'validated' and 'earnings' 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 readOnly, idempotent, and non-destructive behavior. The description adds useful context by listing the specific metadata returned and confirming that only accessible graphs are listed, 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?

Two sentences, front-loaded with the core action and result fields, followed by usage guidance. Every sentence contributes value with zero 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 simple list tool with one optional parameter and no output schema, the description adequately covers what is returned, when to use it, and how it relates to the rest of the toolset. It is self-sufficient for correct invocation.

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

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

The single optional parameter (userId) is fully described by the schema at 100% coverage. The description adds no new parameter semantics; the schema already explains optionality and authentication, so baseline 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 lists all expert knowledge graphs the user can access, enumerates the returned fields (IDs, descriptions, authors, sectors, signal counts, topic coverage), and distinguishes it from sibling search tools by positioning it as the discovery 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?

Explicitly instructs to use 'FIRST in any session to discover available sources before searching' and explains that returns graph metadata needed for graphId parameters in other tools, creating clear when-to-use and relationship-to-siblings 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 mark the tool as read-only and idempotent; the description adds valuable behavioral specifics, namely that the tool extracts 'clean text' and returns 'structured text ready for analysis.' It does not disclose failure behavior, such as unsupported URLs or restricted-content issues, but for this simple read tool the annotations cover the main risk profile.

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 tight sentences: it delivers the primary action first, then the main-use context, then the output shape. Every sentence earns its place 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-required-parameter, read-only tool with no nested objects, the description explains what it does, when to use it, and what kind of output is expected even though no output schema is declared. It would be richer if it handled failure cases or non-HTML URLs, but nothing critical is missing for an agent to invoke this 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%, and both `url` and `userId` are already described in the schema. The tool description stays safe, so no additional parameter semantics is needed; at the same time, it provides no later parameter meaning beyond what the schema already states.

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

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

The description states a specific verb and resource: 'Extract clean text content from any URL.' It also names a concrete scenario (user-shared links like competitor sites, news articles, briefs, trend reports), which makes the tool's purpose unambiguous and distinguishes it from the surrounding graph-query 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?

It gives an explicit trigger: 'Use this when a user shares a link...' and gives representative examples. It does not name alternatives or exclusions, but none of the listed siblings overlap with URL content extraction, so the guidance is practical and sufficient.

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 readOnlyHint, openWorldHint, and non-destructive behavior, lowering the bar. The description adds substantial behavioral context by specifying the parallel search over all accessible graphs when graphId is omitted and by describing the return value shape: trend data with cited evidence, source attribution, and lifecycle stage. This goes beyond what the annotations alone 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?

The description is concise and front-loaded, stating the core purpose in the first sentence and then adding default behavior and use cases. Every sentence contributes value, and there is no filler or repetition. It remains easily scannable for an AI agent choosing a tool.

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 tool with 9 parameters and no output schema, the description provides high-level output expectations (cited evidence, attribution, lifecycle stage) and default behavior. It integrates well with the comprehensive schema, though it does not serve to explain what each of the more nuanced parameters like mode or graphs does. With schema coverage at 100%, this is sufficiently 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%, and all parameters already have detailed descriptions in the schema. The tool description does mention the graphId default and that omitted graphId searches all graphs, but this information is also present in the schema. Since the schema carries the full burden, the description adds no significant extra param semantics beyond 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?

The description opens with a specific verb and resource: 'Find trends, signals, and expert insights across 100+ curated knowledge graphs.' It clearly distinguishes itself from generic web search by noting that it returns cited evidence and lifecycle stage, not generic web summaries. However, it does not explicitly differentiate among sibling search tools like search_insights or search_statistics.

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 guidance on when to use the tool: 'Use for market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts, or any topic where curated expert intelligence outperforms web search.' It also gives a strong default recommendation to omit graphId and search all graphs. Missing explicit exclusions with respect to alternative sibling tools.

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

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

Annotations already convey readOnly and non-destructive behavior, so the description's additional burden is lower. It adds valuable behavioral context: results are qualitative evidence (quotes, interpretations) with source attribution and parent trend context, and it explicitly states what the tool is NOT for (raw numbers). This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the most important 'NARRATIVE only' distinction, names a sibling alternative, and closes with a clear usage criterion. It is slightly repetitive (reiterating 'NOT raw numbers' and mentioning search_statistics twice within the description and schema), but each sentence still carries meaningful value and the overall length is reasonable.

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, but the description compensates by describing the return characteristics: quotes, interpretations, source attribution, and parent trend context. It also covers graph applicability and when to use alternative tools. It could mention pagination or limit behavior more explicitly, but the essential information for correct selection and invocation is 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?

Schema description coverage is 100%, so the schema already documents every parameter thoroughly. The description adds high-level conceptual framing but does not substantially expand on parameter-level semantics beyond what the schema provides. A baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific verb-resource pair ('search' + 'insights') and clearly defines the scope: narrative-only content such as expert quotes, editorial analysis, and strategic perspectives from named strategists. It explicitly contrasts with raw data tools and names what differentiates it, so an agent can distinguish it from search_statistics without ambiguity.

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 tells the agent when to use this tool: when needing authoritative voices, strategic framing, or analytical depth. It also names the alternative for hard numbers and market data: search_statistics. It adds the important constraint that it works on ALL graphs, making the decision rule complete.

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

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

Annotations already mark the operation as read-only and non-destructive, and the description adds useful behavioral context: results link back to expert trends, 'HARD NUMBERS only' restricts the output, and the tool works across all graphs. It also advises searching multiple graphs for better coverage. There is no contradiction with the annotations.

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

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

The description is succinct yet information-dense. It front-loads the core purpose ('HARD NUMBERS only'), immediately follows with usage guidance, and closes with a short alternative and scope clarification. No filler exists; each sentence contributes to tool selection and successful invocation.

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 search tool with six parameters, required graph_id and query, and no output schema, the description provides enough complete context: it defines the result content, explains the linking behavior to expert trends, states graph scope, and gives a clear selection heuristic. It also mentions coverage across multiple graphs, which helps an agent plan calls.

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 explains all parameters. The description adds little new detail about individual parameters, though it does emphasize that graph_id can target all graphs and recommends searching multiple graphs. This is a baseline score because the schema carries the main parameter burden.

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

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

The description names a specific action and resource ('search statistics'), states 'HARD NUMBERS only', and enumerates the content type (figures, market sizes, growth rates). It clearly distinguishes itself from search_insights, which handles quotes and narrative, making it easy for an agent to select the right tool.

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 usage conditions are given: 'Use when a question asks for a number or statistic — try this BEFORE supplemental data tools.' It also names the alternative search_insights and the conditions under which to use it (expert quotes, editorial analysis, narrative interpretation), leaving no ambiguity about when to choose each tool.

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