Fodda Topic & Trend Research

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful behavioral details: polling frequency, expected statuses, and result retrieval.

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 purpose and usage, no wasted words. Every sentence adds distinct 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?

Reasonably complete for a simple polling tool. Lacks explicit output format, but mentions COMPLETE and FAILED statuses and result retrieval, which is adequate for a status check.

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 has 100% coverage with job_id described as 'The Job ID returned by get_supplemental_context'. Description reinforces this context, adding value beyond 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 checks if market data gathering is complete and retrieves results, distinguishing it from the sibling get_supplemental_context which initiates the job.

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 call after get_supplemental_context and poll every 5-10 seconds until status is COMPLETE or FAILED, providing clear when-to-use and when-not-to-use 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds details about return content (citations, publisher attribution, source URL, etc.) and that it's a direct lookup, enhancing transparency beyond 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 concise three-sentence paragraph, front-loaded with purpose, followed by usage guidance and behavioral note. Every sentence 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?

Given no output schema, the description lists all return fields (source URL, location, brand names, publication date, category, formatted citation) and provides complete guidance on input parameters and usage context, addressing the tool's complexity well.

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 detailed parameter descriptions. The description adds minor usage context (e.g., using after search_graph) but does not significantly extend schema semantics. Per guidelines, 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 retrieves source articles, case studies, and statistics behind a trend with citations, specifying the action and resource. It distinguishes from siblings by noting it's a direct lookup by trend ID, not a text search 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?

Explicitly advises using after search_graph, explains how to obtain graphId and for_node_id, and includes warnings against guessing node IDs or passing trend names.

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

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

With annotations already marking it read-only and idempotent, the description adds behavioral context: it returns lists, and for Trend label it is a full deterministic list. Does not contradict 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 with clear examples, front-loaded with purpose. 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?

Given no output schema and 4 parameters, the description covers the main purpose and a key usage nuance (Trend label completeness). Could hint at output format but overall sufficient.

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. The description mentions label values and the special Trend case but does not add meaning beyond the schema for other parameters like userId and property.

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 states that the tool lists labels (brands, locations, etc.) within a knowledge graph, with specific examples ('what brands are in the retail graph?'). Distinguishes from siblings that focus on single nodes or neighbors.

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 use cases: explore graph contents, and special guidance for using label='Trend' to get a deterministic list. Does not explicitly exclude sibling tools but provides strong contextual cues.

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. Description adds value by noting returns live data not cached, which is a behavioral trait beyond 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 only, each serving a clear purpose: listing outputs and specifying when to use. No wasted 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?

Given no output schema, description adequately lists return fields and usage. Could optionally detail response structure, but overall complete for a simple account check 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?

No parameters; schema coverage is 100% trivially. Description does not need to add parameter info, so baseline 4 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 uses specific verb 'check' and resource 'account status', listing concrete fields (API call balance, plan, enabled/disabled graphs, profile info). It clearly distinguishes from siblings by referencing user queries like 'how many API calls do I have?'.

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?

Description provides explicit usage examples (user questions) and contexts, but does not mention when not to use or suggest alternatives like check_supplemental_status.

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 idempotentHint=true. The description adds functional context (what data is returned) but does not disclose additional behavioral traits beyond annotations. It is consistent. With annotations present, the bar is lower, but the description adds minimal behavioral depth.

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: purpose, then usage context and requirement. Front-loaded, no filler, every sentence 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?

Given 3 parameters, no output schema, and rich annotations, the description covers tool function, usage context, and prerequisite. It lists returned fields but omits pagination or error behavior. Near complete for a read-only 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 baseline is 3. The description reiterates the node_id constraint but adds no new semantic detail beyond the schema descriptions. No parameter-level enumeration or format guidance.

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 gets the full profile of a specific trend, listing included fields (lifecycle stage, signal strength, etc.), and distinguishes it from the sibling search_graph which returns summaries.

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 advises to use after search_graph returned a summary, and requires a node_id from that prior result. This provides clear when-to-use and prerequisite 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 indicate readOnlyHint=true, and description confirms retrieval behavior ('retrieves data', 'fanned out in parallel'). Adds cost info ('5 tokens, $2.50 via SPT') and mentions 80+ sources. No contradiction with annotations. Could elaborate on pagination or timeouts, but overall good.

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 very concise: three sentences plus a note. It is front-loaded with the core purpose, then adds details on when to call, data sources, and cost. Every sentence adds value with 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?

Given the tool's complexity (5 params, 1 required, no output schema), the description covers the main use case, trigger condition, data sources, cost, and output format ('categorized data blocks with source attribution and metadata'). It is complete enough for an agent, though could mention rate limits or error scenarios.

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 parameters. The description does not add significant new semantic information beyond the schema; it lists example sources but those are not parameter-related. 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's purpose as a standard layer for macro, institutional, and real-time market data. It specifies when to call (thin/empty coverage or demand-shaped queries) and distinguishes from siblings by referencing search_graph's coverage annotation.

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 states when to use the tool (thin/empty coverage, demand-shaped queries) and provides a concrete example (search volume, economic series, census data). Also gives a note about calling after search_graph indicates thin/empty coverage, linking to a sibling. Lacks explicit when-not-to-use guidance, but positive guidance is strong.

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 provide readOnlyHint and destructiveHint, so bar is lower. Description adds value by detailing the return metadata (required for graphId parameters) and deprecated values, which is 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?

The description is four sentences, front-loaded with the action and results, followed by usage advice and deprecation notes. Every sentence adds value with 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?

Given the simple tool (one optional parameter, no output schema), the description adequately covers what it does, what it returns, how to use it in a session, and deprecations. It is complete for an agent to select and 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?

Schema coverage is 100% with a clear description of the optional userId parameter. The tool description does not add any additional meaning beyond the schema, 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?

Description clearly states 'List all knowledge graphs the user can access' with specific details (IDs, descriptions, authors, sectors, signal counts). It distinguishes from siblings by advising to use first to discover sources before searching, implicitly differentiating from tools like search_graph that require graphId.

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 'Use FIRST in any session to discover available sources before searching,' providing clear when-to-use guidance. It also lists deprecated graphs, serving as when-not-to-use. However, it does not explicitly exclude alternative 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 declare readOnly and idempotent. Description adds cost information (15 tokens) and output format, enhancing transparency beyond 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?

Three sentences, front-loaded with purpose. Efficiently adds context (usage, cost) without superfluous text.

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?

Adequately covers inputs, outputs, cost, and use case. No output schema, but description explains return type as 'structured text'. Appropriate for a simple 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 descriptions for both parameters exist. Tool description does not add extra detail beyond what schema provides, meeting 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?

Clearly states the action ('extract clean text content') and the resource ('any URL'). Distinguishes from siblings like search_graph and get_node, which do not perform URL extraction.

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 explicit when-to-use scenarios (user shares a link for cross-referencing), but lacks explicit when-not-to-use or alternatives. Context is sufficient for most agents.

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 readOnlyHint=true, and description adds behavioral details: returns lifecycle stage, cited evidence, source attribution, not generic summaries. No contradictions. Adds value beyond annotations regarding output format and scope.

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 concise sentences front-loading purpose, then a recommendation sentence. No fluff; every sentence adds value. Efficient structure for an AI 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?

No output schema, but description explains return includes evidence and lifecycle stage. Covers main use cases and default behavior. Could mention edge cases or performance, but sufficient for selection and basic 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 has 100% coverage with descriptions. Main description adds context for graphId ('recommended default to search all') and mode (explains API call counts). Provides concrete graph ID examples. Adds moderate meaning beyond 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?

Description clearly states the tool's purpose: 'Find trends, signals, and expert insights across 100+ curated knowledge graphs... Returns trend data with cited evidence, source attribution, and lifecycle stage'. It distinguishes from generic web search, making the resource and action specific.

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 use cases: 'market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts'. Recommends default behavior (omit graphId to search all). No explicit when-not-to-use, but the context is 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 declare readOnlyHint=true and destructiveHint=false. The description adds that returns are qualitative (quotes, interpretations) with source attribution and parent trend context, confirming safe read behavior and providing details beyond 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, front-loaded with key information, no wasted words. Each sentence contributes unique value: first defines scope and content type, second guides usage and alternatives.

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 explains the nature of returns (qualitative evidence with attribution and context). It covers the tool's domain and input parameters well, though could mention pagination or format details.

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 detailed descriptions for each parameter. The description reinforces parameter meaning (e.g., 'NARRATIVE only' for types) but does not add significant new semantic value beyond the schema's existing explanations.

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 it returns 'NARRATIVE only' content like expert quotes and strategic perspectives, distinguishing it from 'search_statistics' for hard data. It specifies the resource (expert insights) and verb (search), and mentions it works on all graphs.

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 when to use this tool vs. 'search_statistics' and when to use it for 'authoritative voices, strategic framing, or analytical depth'. It also advises searching across multiple graphs for best coverage.

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. The description adds behavioral context: results 'link back to the expert trend it supports' and that it retrieves 'curated' data from experts. 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 establishes purpose and behavior, second gives usage guidelines. Every sentence earns its place with high information density and 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?

Given 6 parameters, 2 required, no output schema, the description fully covers the tool's purpose, scope, behavior, and usage context. It mentions graph coverage, linking behavior, and when to prefer this tool over siblings. No 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 coverage is 100%, so baseline is 3. The description adds value by explaining the 'query' parameter with concrete examples (e.g., 'luxury resale market size'), specifying the 'graph_id' domain (PSFK curated graphs plus expert graphs), and giving usage advice for 'min_score' (0.60 for broad, 0.70+ for precise).

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 explicitly states it returns 'HARD NUMBERS only: specific figures, market sizes, growth rates, and quantitative data points'. It distinguishes itself from the sibling 'search_insights' by specifying that tool handles 'expert quotes, editorial analysis, and narrative interpretation'. The verb 'search' with resource 'statistics' is clear.

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 guidance: 'try this BEFORE supplemental data tools' and tells when to use the alternative 'search_insights' for non-quantitative needs. It also clarifies scope: 'Works on ALL graphs' and advises searching multiple graphs for best coverage.

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