Fodda Earnings Intelligence

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by stating 'Returns a branded SVG that renders directly in the chat,' which clarifies the output format and rendering behavior 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 a single sentence that front-loads the core purpose and then enumerates chart types. It is efficient but the list of chart types is lengthy and partially redundant with the schema's enum and data description, though it does provide quick reference without needing to consult the schema.

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

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

Given only 2 parameters, no output schema, and full schema coverage, the description is relatively complete. It provides the return type (SVG) and rendering behavior, which is important for an agent to set expectations. However, it doesn't explicitly note that the tool is read-only or idempotent, but annotations cover that.

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 both parameters (data and chart_type) fully described. The description's inline chart type explanations (e.g., 'cultural_shifts' as From→To transitions) mostly duplicate the schema's data property description, so the description adds little 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 uses a specific verb+resource: 'Create a presentation-ready data visualization from research findings.' It clearly distinguishes itself from sibling tools, which are all get_* retrieval tools, by being the only generation tool. The list of chart types further clarifies its unique purpose.

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 context with 'from research findings' and lists available chart types, giving clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives, though the sibling tools are all reads so exclusion is implicit.

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, so safety is covered. The description adds context about content (capabilities and pricing) but does not disclose additional behavioral traits such as rate limits, auth needs, or the effect of the optional userId parameter.

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 action, and contains no unnecessary words. It efficiently conveys purpose and usage guidance.

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 simplicity (one optional parameter, no output schema, strong annotations), the description sufficiently covers what the tool returns (capabilities and costs) and when to use it. No critical information is missing for an agent to select and invoke it correctly.

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

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

The schema covers 100% of the parameter (userId) with a description, so the baseline is 3. The description does not add any meaning beyond the schema; it doesn't explain how userId affects the response, but the schema already documents it adequately.

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 Fodda's main capabilities, features, offerings, products, services, tools, and their costs. It uses a specific verb ('Returns') and identifies the resource, and the scope is distinct from sibling tools like get_company_earnings or get_my_account.

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

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

It explicitly instructs to call this for any question about what Fodda can do or what's available, providing clear when-to-use guidance. However, it does not mention when not to use it or name alternative tools, so it stops short of a perfect score.

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 known. The description adds value by disclosing the coverage scope (517 consumer-sector companies), the fallback to web-backfill for uncovered tickers, and pricing ($20 per query, coverage free). These details go beyond what annotations provide, though it doesn't discuss rate limits or authentication.

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, each earning its place: a strong lead defining the tool, a detailed summary of return content, a note on fallback and pricing, and explicit sibling differentiation. It is front-loaded with the most important information and contains no fluff.

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 description conveys what the tool returns (full record contents), its scope, pricing, and usage context. Given there is no output schema, the description serves as the primary source for return information. It could be slightly more detailed about error cases or exact view behavior, but the schema covers view semantics, so overall it is reasonably 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?

Input schema has 100% coverage with detailed descriptions for all 9 parameters, including the 'view' enum explanations. The description itself adds little parameter-specific detail beyond referencing the general output and the ticker scope. Since the schema fully handles parameter semantics, 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 opens with 'The canonical per-ticker earnings source,' clearly identifying the tool's purpose (per-ticker earnings data) and then specifies what it returns (full truth-layer record, analyst concerns, sentiment, strategic activity, CEO intelligence, validated trends). It explicitly distinguishes itself from sibling get_earnings_intelligence by noting 'Use get_earnings_intelligence for cross-company thematic comparisons.' This is a specific verb+resource with clear differentiation.

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 usage guidance: 'Use this for company-specific data. Use get_earnings_intelligence for cross-company thematic comparisons.' It also mentions fallback behavior for uncovered tickers and notes that the coverage view is free, giving practical context on when to invoke the 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 indicate read-only and non-destructive behavior, so the description adds value by noting the legacy-thematic nature, cross-company scope, and pricing. It also clarifies output semantics (the gap between analysts and management responses). However, it doesn't discuss data coverage limitations, but given strong annotations, this is above 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 four sentences, front-loaded with the main purpose, followed by usage, alternative, and price. No redundant or filler content.

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

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

With no output schema, the description gives a functional understanding of what is returned (deflecting/reframing behavior). It includes pricing, scope, and an alternative path, making it reasonably complete for a read-only analysis tool with 7 parameters that are already well-documented.

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 all parameters already described with examples (e.g., search includes 'tariffs', 'AI capex'). The description does not add additional parameter-level detail, so the baseline 3 applies.

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

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

The description clearly states the tool detects cross-company analyst-management divergence from the knowledge graph, and explicitly differentiates from siblings by referencing get_company_earnings for per-ticker deflection signals. The verb 'detect' and the resource 'divergence' are specific and non-tautological.

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 explicit use cases ('where are executives deflecting?', 'divergence in [sector] earnings') and gives an alternative tool with specific instructions ('use get_company_earnings with view=qa and filter by response_directness'). This gives clear when-to-use vs. alternative 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 and destructiveHint=false, so the safety profile is known. The description adds useful context beyond annotations: results may include 'knowledge_graph' or 'web_supplemental' provenance, and it discloses the $30 per query cost. This exceeds the minimal bar set by 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 long and front-loaded with purpose. Each sentence earns its place: purpose, usage guidance, alternative tool comparison, and provenance/cost. There is no wasted wording or duplication of schema content.

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 effectively sets expectations by mentioning provenance and pricing. It covers when to use, alternatives, and filtering concepts. The only minor gap is not explicitly discussing filter combination rules, but the schema already notes 'At least one filter required' on the ticker parameter, and the overall guidance is sufficient 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 description coverage is 100% (all 9 parameters have individual descriptions), so the baseline is 3. The description adds only a concrete example ('labor costs') and reinforces sector/industry filters, without introducing new per-parameter semantics. It doesn't compensate for the lack of enums or required fields, but the schema handles those.

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 ('Cross-company thematic earnings intelligence from the knowledge graph and web sources') and clearly distinguishes itself from siblings like get_company_earnings (per-ticker structured analysis) and brand_tracker (single-brand earnings). It leaves no doubt about the tool's core purpose.

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

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

It explicitly prescribes when to use the tool: 'Use for multi-company comparisons... industry-level queries, or sector filters.' It also provides exclusions and alternatives: 'For single-brand earnings, brand_tracker includes earnings automatically. For per-ticker structured analysis... use get_company_earnings instead.' This is exemplary usage 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 read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations, including pricing ($0.50 per lookup) and details about the output structure (source URL, location, brand names, publication date, category, formatted citation). No contradiction with 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 concise with four sentences, each adding value: purpose, output contents, usage context, and a clarification of its direct lookup nature. No fluff or redundancy; 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?

Despite lacking an output schema, the description effectively explains return values (each item includes source URL, location, brand names, publication date, category, and formatted citation). It also covers pricing and operational context, making it complete for invoking 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 descriptions cover 100% of parameters, providing detailed guidance for graphId and for_node_id. The description adds meaning by clarifying that for_node_id comes from search_graph results and warns against guessing IDs, which complements the schema and helps correct parameter usage.

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. It explicitly differentiates itself from search tools by noting it's a direct lookup by trend ID, distinguishing it from siblings like 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 provides explicit usage context: 'Use after search_graph when you need the supporting proof behind a trend.' It also states what the tool is not ('not a text search tool'), giving clear guidance on when to use it versus 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?

The annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds valuable behavioral context: the label="Trend" call returns a 'full deterministic list', and it notes that search may return partial results, implying this tool is more reliable for complete enumeration of trends. 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?

The description is three sentences, each earning its place: the first states the core function, the second explains when to use it with examples, and the third provides a targeted tip for a specific label. It is front-loaded 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 tool is a simple list function with required parameters clearly described in the schema, the description is complete enough. It covers purpose, usage examples, a special-case instruction, and the comparison to search. The only omission is the return format, but since there is no output schema and the purpose is self-evident, this is a minor gap.

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

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

The input schema already provides 100% coverage with descriptions for all parameters, including examples for label and graphId. The description reinforces the label parameter with a special usage case (Trend) and gives illustrative graph queries, but it doesn't add significant new semantics that aren't already present 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 opens with a specific verb and resource: 'List all brands, locations, technologies, audiences, or trends within a specific knowledge graph.' It clearly identifies the tool's function and differentiates it from siblings like get_node or search_graph, which focus on individual nodes or search behavior.

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 concrete usage context: 'Use to explore what a graph contains' and gives example queries. It also includes a special directive for label="Trend" to obtain a complete list when search may return partial results. While it doesn't explicitly name alternatives, the guidance effectively tells the agent when this tool is preferable.

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, so the safety profile is covered. The description adds valuable behavioral context by stating 'Returns live data — not cached from session start', which is not captured in the annotations, giving the agent insight into data freshness.

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 exactly two sentences, front-loaded with the action and resource. The first sentence states purpose, the second gives usage triggers and a key behavioral trait. 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?

For a zero-parameter, read-only account status tool with comprehensive annotations, the description fully covers purpose, usage, and live-data behavior. No output schema is needed since the description enumerates the key return categories, and the tool's simplicity means nothing essential is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description compensates by listing what information the tool returns (balance, plan, graphs, profile), which helps the agent understand the output even without an output 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 starts with a specific verb 'Check' and names the resource 'current user's account status', listing concrete elements: API call balance, plan, enabled/disabled graphs, and profile info. This clearly distinguishes it from sibling tools that focus on graph data like list_graphs 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 provides explicit when-to-use scenarios with example user questions ('how many API calls do I have?', 'what plan am I on?', 'what graphs can I access?'). It lacks explicit exclusions or alternative tool references, but the context is clear enough for a zero-parameter account-specific 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 cover readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds valuable behavioral context: it requires a valid node_id from a prior search_graph result, and notes that results are curated editorial connections not available via web search. No contradiction with 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 purpose, and each sentence contributes. However, the first two sentences are slightly redundant ('that search alone wouldn't surface' vs 'that web search cannot provide'), which costs a point for conciseness.

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 7 parameters, no output schema, and rich annotations, the description covers the crucial prerequisite (node_id from search_graph) and explains the tool's unique value (curated editorial connections). While it does not detail response structure, the description gives sufficient context for a graph-neighbor discovery 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 schema has 100% parameter description coverage, so baseline is 3. The description largely repeats the seed_node_ids requirement already stated in the schema ('Requires node_id from a prior search_graph result') without adding new parameter-specific semantics or examples 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 starts with a specific verb 'Discover' and names the resource ('what's connected to a specific trend'), then details contents (brands, technologies, locations, cross-domain links). It explicitly distinguishes itself from search_graph by positioning as an after-step for mapping territory, which differentiates it from siblings.

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

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

The description gives clear usage context: 'Use after search_graph to map the territory around a trend, find which brands are connected, or understand cross-domain relationships.' It implies the prerequisite of search_graph and the kinds of questions it answers, but does not state when not to use the tool or mention 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context by specifying that node_id must come from a prior search_graph result and by outlining the returned fields, which is 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?

Three focused, well-ordered sentences. The first states the action and contents, the second the use case, and the third the prerequisite. No filler or redundant content.

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 compensates by detailing the return contents. It also covers the dependency on a prior search_graph result and the intended use case. Combined with the rich schema and annotations, this is complete for a read-only, single-node lookup tool.

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

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

Schema description coverage is 100%, with rich descriptions for nodeId and graphId. The description's mention of requiring node_id reinforces but does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource ('Get the full profile of a specific trend') and enumerates the contents ('detailed description, lifecycle stage, signal strength, geographic scope, and all properties'). It clearly distinguishes this from the sibling search_graph tool, which is described as returning 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?

The description explicitly states when to use it: 'Use when you need deeper detail on a single trend after search_graph returned a summary.' It also identifies the key prerequisite: 'Requires node_id from a prior search_graph result.' It does not enumerate exclusions or alternative tools, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the cross-validation pipeline and the $25 per query cost, but it does not disclose rate limits, pagination behavior, or authentication requirements, which would be useful for a paid query tool.

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

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

The description is three concise sentences: purpose, methodology/context, and pricing. It is front-loaded with 'Returns', contains no redundant language, and every sentence conveys distinct information without fluff.

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 query tool with fully described parameters and safe annotations, the description covers purpose, cost, and methodology. However, the lack of an output schema means the agent cannot infer the return structure, and the description does not specify what fields are in each trend object or how results are paginated, which slightly reduces 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%, so all parameters (limit, search, sector, ticker, userId) have descriptions. The tool description adds some context by noting the connection between earnings commentary and consumer trends, but it does not elaborate on parameter usage or constraints beyond what the schema provides, 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 states a specific verb ('Returns') and resource ('market-validated consumer trends from corporate earnings reports'), clearly distinguishing it from sibling tools like get_company_earnings or get_earnings_intelligence. It also adds unique methodology context (cross-validated by Fodda's analysis pipeline) that differentiates its purpose.

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 does not provide guidance on when to use this tool versus alternatives. It doesn't mention exclusions, alternative tools, or specific scenarios for which this tool is preferred. The pricing note is useful but does not constitute usage guidelines.

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 description only needs to add context. It adds valuable detail about permission filtering ('the user can access') and the return content (metadata needed for graphId parameters), which is useful 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 two sentences: the first states the purpose and return contents, the second provides usage guidance and its relationship to other tools. Every word adds value, with the key information front-loaded. 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 simple list tool with one optional parameter, no output schema, and safe annotations, the description sufficiently covers what the tool does, what it returns, and how to use it in a session. It fully compensates for the absence of an output schema by enumerating the fields returned.

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 the single optional parameter (userId) with a complete description, achieving 100% schema coverage. The tool description itself does not add additional meaning to the parameter beyond what the schema provides, so a 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?

The description clearly states the verb 'List' and the specific resource 'expert knowledge graphs the user can access', enumerating exact fields returned (IDs, descriptions, authors, sectors, signal counts, topic coverage). This differentiates it from sibling tools like search_graph or get_node, which serve different purposes.

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 instructs to 'Use FIRST in any session to discover available sources before searching', providing clear when-to-use context. It also explains that the tool returns graphId parameters needed by other tools, but does not mention explicit when-not-to-use scenarios or alternatives beyond the general search context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable context: return payload (cited evidence, source attribution, lifecycle stage), cost ($20 per query), and the parallel search behavior when graphId is omitted. It does not contradict annotations and enriches the agent's understanding of operational traits.

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 focused paragraph with no filler. It front-loads the core purpose, then adds practical details (return format, cost, default behavior, use cases). Slightly long but every sentence adds usefulness; not repetitive.

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 complex (8 parameters, no output schema), but the description covers purpose, scope, return payload, pricing, default graph behavior, and use cases. It lacks explicit result structure and pagination details, but for a read-only search tool with robust schema descriptions, this is sufficient. It also mentions an alternative tool for sub-national data.

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 baseline is 3. The description mentions graphId's default behavior and query semantics (e.g., country/regional filtering), but these are also fully documented in the schema. No additional parameter insights beyond what the schema provides, so no score above 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 clearly states the tool searches across curated knowledge graphs to find trends, signals, and expert insights, covering specific domains. It differentiates itself from web search and sibling tools by emphasizing curated graphs, cited evidence, and lifecycle stages. The scope (100+ graphs) and output type are explicitly defined.

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 use cases (market trends, competitor analysis, etc.) and states that it is for topics where curated expert intelligence outperforms web search. It also provides a recommended default behavior (searches all graphs), and the schema description directs users to get_supplemental_context for sub-national data, offering a clear alternative.

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