Fodda Earnings Intelligence

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: it returns a branded SVG that renders directly in chat, lists the chart-type-specific transitions, and explains the focus highlighting mechanism. 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 dense but every sentence earns its place: primary purpose, chart type list with meanings, output format, and focus highlighting. It is front-loaded with the main verb and resource, and the chart list is necessary for a tool with six distinct subtypes.

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 6 chart types and no output schema, the description covers the return format (SVG) and all chart variants. The input schema handles the detailed data structures. Minor gaps remain, such as explicit guidance on when each chart type is most appropriate, but overall the agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with the data parameter's schema description containing detailed per-chart-type JSON formats. The tool description adds semantic meaning beyond the schema by explaining what each chart type represents (e.g., 'cultural_shifts' (From→To transitions), 'opportunity_map' (2×2 white space analysis)), helping the agent choose correctly.

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: 'Create a presentation-ready data visualization from research findings.' It enumerates all six chart types with clarifying parentheticals, clearly distinguishing this tool from the get_*/list/search sibling tools that retrieve data rather than generate visuals.

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 phrase 'from research findings' and 'presentation-ready' provide clear context for when to use this tool. It does not explicitly name alternatives or exclusions, but the sibling tools are all data retrieval/search operations, making the use case unambiguous. It could be stronger with an explicit 'use this instead of X when a visual is needed' statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing a safe read-only operation. The description adds helpful context about the returned content (features, offerings, how-to-use), but no additional behavioral detail like response size or scoping is provided.

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 delivers the purpose in one efficient first sentence and usage guidance in a second. It front-loads the core action, is appropriately sized, and contains no filler or repetition.

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

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

For a simple optional-parameter read-only tool, the description covers what is returned and when to use it. Since there is no output schema, the description appropriately explains the return scope without over-specifying.

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 the only parameter, userId, with a description ('Optional user identifier.'), so the schema itself carries the parameter semantics. The tool description adds no additional meaning about how the optional userId affects the result.

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 what the tool does: it returns Fodda's main capabilities, offerings, and usage instructions. It explicitly orients the agent to use it for any question about what Fodda can do, differentiating it from the more specific sibling data-retrieval tools.

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

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

The description provides clear guidance on when to call it: 'Call this for any question about what Fodda can do or what's available.' It does not explicitly mention when not to use it or name alternatives, but the context is unambiguous.

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, so the description need not repeat that. It adds non-obvious behavior by describing coverage of 517 consumer-sector companies and the web-backfill fallback path. 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 front-loaded with the per-ticker purpose, then gives useful content expectations, then states fallback behavior and sibling routing. Every sentence carries operational value and there is no filler or vague marketing language.

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

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

For a read-only tool with a fully documented 9-parameter schema, the description provides a strong mental model of what the tool returns and what it can do for covered vs. uncovered tickers. The lack of a detailed return schema means the description cannot fully specify output shape, but it names the major record components clearly.

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?

Parameter schema coverage is 100%, so the description is not required to explain each parameter. It adds some output-oriented context, such as what a record contains, but it does not add semantic meaning for view, period, mode, tickers, or sector beyond what the schema already gives. 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 identifies this as the canonical per-ticker earnings source and states its specific contents: analyst concerns, sentiment labels, strategic activity, CEO intelligence, and validated consumer trends. It also differentiates the tool from get_earnings_intelligence, which is the key sibling 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?

It explicitly routes usage: 'Use this for company-specific data' and 'Use get_earnings_intelligence for cross-company thematic comparisons.' It also tells the agent that uncovered tickers fall back to web-backfill, which helps an agent decide whether this tool can handle an out-of-coverage query.

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 read-only and non-destructive behavior. The description adds meaningful context: results are cross-company, sourced from a 'legacy-thematic' knowledge graph, and focus on the gap between analyst pressure and management response. It does not describe output format, but the annotation coverage lowers the burden here.

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

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

The description is compact, front-loaded with the primary purpose, provides examples, and then routes to the relevant sibling. Every sentence earns its place; 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 no-output-schema, all-optional-parameter tool, the description explains what the tool is for, what kind of signals it surfaces, and how to distinguish it from related tools. The only gap is that it does not explicitly state the format of the returned divergence data, but the conceptual output is described well enough for initial selection and invocation.

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

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

Schema description coverage is 100%, and the schema already provides parameter examples for 'search', 'sector', and 'industry'. The description adds no unique parameter-level details, so it aligns with the baseline for high schema coverage.

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 the tool's function: cross-company analyst-management divergence detection from the knowledge graph. It adds concrete conceptual detail (executives deflecting, reframing, avoiding topics) and distinguishes itself from the sibling get_company_earnings, making it unambiguous among the sibling set.

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-case phrasings ('where are executives deflecting?' or 'divergence in [sector] earnings') and explicit when-not-to-use guidance with an alternative tool: 'For per-ticker deflection signals, use get_company_earnings with view=qa and filter by response_directness.' This is the strongest form of 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 cover read-only and non-destructive behavior. The description adds context beyond those: it combines knowledge graph and web sources, and discloses that results may have a knowledge_graph or web_supplemental provenance. That helps the agent set expectations about result source quality and inconsistency, while not over-performing.

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

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

Four short sentences, each earning its place: purpose, use cases, sibling alternatives, and provenance behavior. The main purpose is front-loaded and none of the text is redundant or promotional.

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 is strong for scope and alternatives, but it never explicitly states the key invocation constraint that at least one filter is required. This is only buried in the ticker parameter description, and no fields are required in the schema, so an agent could plausibly call it with no filters. With 9 parameters and no output schema, the lack of a single-line invocation rule leaves a meaningful gap despite good overall prose.

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 input schema already documents every parameter with examples ('labor costs', 'NKE', 'hotels'). The description reinforces the query intent and theme filters but adds little beyond what the schema already provides. This is a typical baseline-3 situation where 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?

States a specific verb-and-resource ('Cross-company thematic earnings intelligence') and clearly differentiates from siblings by naming get_company_earnings and brand_tracker as alternatives. An agent can understand that this tool targets thematic, multi-company comparison rather than per-ticker or single-brand earnings.

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 tells when to use this tool: for multi-company comparisons, industry-level queries, or sector filters. It also names exclusions: single-brand earnings should use brand_tracker, and per-ticker structured analysis should use get_company_earnings. This gives the agent clear routing guidance without needing to open sibling schemas.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by naming the direct-lookup-by-ID nature, the non-search semantics, and enumerating the fields returned for each evidence item, which goes beyond the annotation information.

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 first sentence says what the tool returns, the second pinpoints when to use it, and the third clarifies what it is not. There is no filler; each sentence earns its place and the 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?

Given there is no output schema, the description compensates by explicitly describing the shape of returned evidence: source URL, location, brand names, publication date, category, and formatted citation. It also connects to the prior search step and warns about direct ID lookup, covering the key operational context an agent needs.

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 four parameters described in the schema, including detailed guidance and examples for graphId and the warning on for_node_id. The description itself adds only marginal semantic reinforcement ('direct lookup by trend ID'), so the schema already 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 clearly states the tool retrieves source articles, case studies, and statistics behind a specific trend, which establishes the verb, resource, and outcome. It also explicitly distinguishes itself from a text search tool, so an agent can differentiate it from search_graph and other 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 explicit guidance: use after search_graph when supporting proof behind a trend is needed, and it clarifies the inverse ('not a text search tool'). This answers when to use it and contrasts it with the most likely alternative without ambiguity.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral nuance beyond that by disclosing that the Trend label returns a full deterministic list, which can differ from open-ended search results. This gives the agent a useful expectation about completeness and determinism.

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 focused sentences with concrete examples and front-loaded imperative phrasing. Every sentence earns its place: first the purpose, then usage context, then a valuable edge-case behavior.

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

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

The description covers purpose, intended usage, and a special-case behavior for the Trend label, which is enough for an agent to invoke the tool in most cases. It could be slightly more complete by explicitly naming the sibling search_graph and describing what to do when the requested label is unavailable, but those gaps are not significant given the rich schema.

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 covers all parameters with rich descriptions, so the baseline is 3. The description adds meaningful label-specific guidance: setting label to 'Trend' returns a complete, deterministic list. That is a useful semantic addition not present in the schema itself.

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

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

The description clearly states a specific action: list label values within a specific knowledge graph. It enumerates what kind of values can be listed and supports it with concrete example queries, which makes the tool's purpose unambiguous and distinct from a general graph-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?

The description gives clear usage context, including example exploratory queries and a specific special case: calling with label="Trend" to get a full deterministic list. It does not explicitly name an alternative tool like search_graph, but it hints that search may return partial results and that this tool should be used when a complete list is needed.

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

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

Annotations already declare readOnlyHint, 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 the read-only, idempotent, non-destructive nature. The description adds that results are 'curated editorial connections' rather than exhaustive raw graph traversal, and it states the dependency on a prior search_graph result. Its mention of 'node_id' rather than the actual schema's seed_node_ids is a minor weakness, so not a 5.

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

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

Three sentences with no fluff. The first sentence immediately states purpose and output; the second emphasizes the editorial differentiator; the third supplies usage context and dependency. Each sentence earns its place and the key 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?

This is a 7-parameter tool with no output schema, but the schema descriptions fully document parameters. The description covers curation, when to use it, and the prior-search_graph dependency. It does not describe the exact return shape, which would be useful with no output schema, but the tool is still usable after reading this description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds that the tool requires a node_id from a prior search_graph result, which reinforces the seed_node_ids parameter but does not go beyond the schema. No additional semantic depth is provided for depth, limit, direction, or relationship types.

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 concrete resource ('connected to a specific trend'), a specific action ('Discover what's connected'), and the types of outputs (brands, technologies, locations, cross-domain links). It clearly distinguishes itself from search_graph by claiming to return editorial connections that web search cannot provide, which separates it from sibling tools.

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

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

It gives explicit context for when to use the tool ('after search_graph', 'map the territory', 'find which brands are connected', 'understand cross-domain relationships'). It does not explicitly name alternatives or say when not to use it, but the placement after search_graph and the limitations of web search provide strong use-case 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add context beyond that. It does so by describing the profile fields returned and the dependency on a prior search_graph result. It does not mention possible operation behaviors like rate limits or result size, but the safety profile is already captured and the description is accurate to those annotations with 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?

Two sentences, no fluff. The first sentence contains the action and output outline; the second contains the call trigger and dependency. Every sentence serves a purpose with no redundant phrases.

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 is well-formed for a read-only retrieval tool with annotations for safety. It gives the trigger and bound key, name and dependency and enough content in terms of what is returned. Since there is no graph known, it could be a little more explicit about how graphId coordinates with nodeId, but the schema fills most of that gap.

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

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

Schema description coverage is 100%, so the baseline under the rubric is 3. The description repeats the node_id prerequisite that is also well documented in the schema (node must come from prior search result), but adds no meaning beyond the schema. graphId and userId are not described in the description, but the schema itself carries enough.

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 clear action and resource: "Get the full profile of a specific trend" and then enumerates the content returned (description, lifecycle stage, signal strength, geographic scope, and properties). It clearly differentiates from sibling tools by placing this as the deeper detail tool that operates on a trend node from search_graph, not on earnings, labels, capabilities, or other resources.

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 guidance is present: "Use when you need deeper detail on a single trend after search_graph returned a summary." It also states the prerequisite: "Requires node_id from a prior search_graph result," which tells an agent when it is appropriate and what it needs before invoke. This is far beyond a mere hint.

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 establish readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: data comes from corporate earnings reports and has been cross-validated by Fodda's analysis pipeline. This explains the provenance and validation behavior without contradicting 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 tightly written sentences with no filler. The primary purpose is front-loaded, and the second sentence adds meaningful context about the source content and signal connection.

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 this is a read-only, idempotent, simple list-like tool with 100% parameter schema coverage, the description is sufficient for an agent to invoke it correctly. It clearly describes the result type and source, though it does not provide details about result structure or sorting, which 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?

Schema description coverage is 100%, so all five parameters already have clear inline documentation. The description adds no additional parameter-level semantics, such as search behavior or sector filtering, 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 states a specific verb and resource: it returns consumer trends derived from corporate earnings reports and cross-validated by Fodda's analysis pipeline. It also clarifies the connection between earnings commentary and trend signals, which helps distinguish this tool from the other earnings-focused 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 implies when to use this tool: when an agent needs market-validated consumer trends tied to earnings commentary. However, it does not explicitly state when not to use it or name alternative tools such as get_earnings_intelligence or get_earnings_divergence, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=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?

The annotations already establish that this is a read-only, non-destructive operation. The description adds genuinely useful behavioral context beyond annotations: searching ALL accessible graphs in parallel when graphId is omitted, the curated-not-generic nature of results, and the lifecycle-stage classification. No contradiction with the readOnlyHint or openWorldHint annotations was identified.

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. Each sentence carries real content: what the tool finds, what it returns and how it differs from web search, and what the default behavior should be. There is no filler or redundant repetition of the tool name or 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?

Even though there is no output schema, the description explains the qualitative nature of the output (trends with evidence, source attribution, lifecycle stage) and the recommended invocation pattern. The input schema covers parameter semantics, and the annotations cover safety, so the description closes the remaining contextual gaps for selecting and invoking 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?

The input schema already documents each parameter well, with 100% coverage. The description adds only a recommendation about omitting graphId and the general search-scope behavior; it does not materially enhance the semantics of individual parameters beyond re-stating what the schema already says.

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 leads with a specific verb and resource: 'Find trends, signals, and expert insights across 100+ curated knowledge graphs.' It further clarifies the output type (trend data with cited evidence, source attribution, lifecycle stage) and explicitly contrasts itself with generic web summaries, which helps an agent distinguish it from siblings like get_validated_trends 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?

It provides clear use contexts: market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts. It also recommends omitting graphId to search all graphs. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool, stopping it short of full routing guidance.

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