Fodda Brand Intelligence

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

The annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: it scans all knowledge graphs, bundles external signals from Google Trends/Wikipedia/Amazon/earnings, and aggregates work that normally requires dozens of separate searches. It doesn't mention latency or cost implications, but for a read-only aggregation tool this is a strong addition 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 well structured: it opens with the core action, follows with a compact list of return components, then provides usage examples and the value proposition. Slightly long, but each sentence earns its place and the most important scoping information ('ALL knowledge graphs') 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 the significant complexity of this tool—no output schema, five parameters, cross-graph and external signal aggregation—the description covers the return shape well. It lists nine output categories and a clear use case. A more detailed description could include how 'bundled supplemental signals' are delivered or whether results are paginated, but the description is sufficient for an agent to understand 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%, so the schema already documents all 5 parameters. The description only adds brand-name example queries like 'Nike' and 'Patagonia', which reinforce but do not materially extend the schema's parameter meaning. This is a solid baseline-with-no-compensation-needed situation.

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 ('Build a complete Brand Intelligence Profile') and a clear resource ('by searching ALL knowledge graphs for a specific brand'). It enumerates rich outputs such as trend footprint, competitive landscape, and cross-graph presence, and it is clearly differentiated from sibling tools like search_graph because it searches ALL graphs and returns aggregated intelligence.

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 says 'Use when the query is about a specific company or brand' and gives concrete example queries. It does not name alternatives or say when not to use this tool, so it stops short of a full usage heuristics with exclusions, but the target usage context is very 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 idempotent, read-only, non-destructive. Description adds key polling behavior: recommended frequency and termination conditions (COMPLETE/FAILED), which goes beyond the annotation's coverage.

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: first states purpose and after-call dependency, second gives polling instructions. No redundancy, optimally 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 the tool's simplicity (1 param, no output schema), the description covers all needed aspects: purpose, when to use, polling pattern, and expected status values. 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 has 100% coverage for the single parameter 'job_id' with a clear description. The tool description does not add additional parameter semantics beyond confirming it's the ID from get_supplemental_context. Baseline score 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?

Description clearly states the tool checks if market data gathering is complete and retrieves results. It specifies the verb 'check', the resource 'supplemental status', and provides context that it should be called after get_supplemental_context, distinguishing 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?

Explicitly states when to use (after get_supplemental_context) and how to poll (every 5-10 seconds until COMPLETE or FAILED). Provides clear usage instructions with no 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?

The annotations already carry readOnly, idempotent, and non-destructive signals, so the safety profile is covered. The description adds genuinely useful behavior beyond annotations: it returns a branded SVG that renders directly in the chat and explains how to highlight a focal entity. There is no contradiction with the annotations.

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

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

The description is three dense, scannable sentences: purpose, chart-type menu, and output/behavior. Every clause contributes new information — chart variety, SVG return format, chat rendering, and focus highlighting. The chart-type list is slightly redundant with the schema enum but serves quick comprehension before an agent opens 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?

For a tool with only two parameters, both exhaustively documented in the schema, this description is complete. It discloses the return format (branded SVG), the rendering behavior, and the optional focus usage. Since there is no output schema, stating the return type is especially valuable. Nothing essential for correct invocation 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?

Schema description coverage is 100%: chart_type is fully enumerated and data has per-chart JSON shapes. The description adds a clear, instructive usage rule for the focus mechanism ('top-level "focus":"Name" or per-item "focus":true'), which goes slightly beyond the schema's structural mention. Some redundancy with the enum exists, but the added guidance earns a 4.

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 object — 'Create a presentation-ready data visualization' — and identifies the source as 'research findings'. It then enumerates six chart types so an agent immediately understands the tool's scope and can distinguish it from the non-visual sibling tools like get_evidence 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 implies it should be used when a presentation-ready visual chart is requested, but it gives no explicit when-to-use, when-not-to-use, or alternative tool guidance. It does help selection within the tool by listing chart types and their conceptual purpose, but it never says what to prefer over other siblings.

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 well covered. The description adds that it returns capabilities and usage instructions, but it does not reveal additional behavioral details such as authentication needs, response shape, or whether userId changes behavior.

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 and efficient sentences. The first states what the tool returns and the second gives the direct trigger condition. No filler, no repetition of annotations, and the most important interpretational content is front-loaded.

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

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

For a simple read-only tool with an optional userId and no required parameters, the description provides enough information for an agent to select and invoke it correctly. It lacks detail about the output format, but no output schema exists and the purpose is exploratory, so 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 only parameter, userId, has full schema description coverage: 'Optional user identifier.' The description adds no extra parameter semantics, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly identifies the purpose: it returns Fodda's main capabilities/features/offerings/tools and how to use them. It also gives a concrete use trigger, which distinguishes it from sibling tools like search_graph, get_node, and get_evidence.

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?

'Call this for any question about what Fodda can do or what's available' explicitly indicates when to use this tool. It does not mention when not to use it or alternatives, but the general capability-discovery nature makes this exclusions less critical.

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 signal read-only, idempotent, and non-destructive behavior, so the description need not restate those. It adds useful behavioral context by enumerating the returned item fields and emphasizing this is a direct ID lookup, which sets accurate expectations 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?

Three focused sentences deliver the core capability, return-value details, and usage context without redundancy. Every sentence is purposeful and the most important information is front-loaded.

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

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

Despite having no output schema, the description explains both the kind of evidence returned and the fields present in each item, such as source URL, publication date, and formatted citation. This provides enough detail for an agent to invoke the tool and interpret its result 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%, and the schema already documents graphId and for_node_id thoroughly, including examples and explicit warnings about not guessing IDs. The description adds only the general 'direct lookup by trend ID' framing without introducing new parameter-specific semantics, so baseline 3 fits.

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 the verb 'Get' with a precise resource: source articles, case studies, and statistics behind a specific trend, including citations and publisher attribution. It explicitly distinguishes itself from a text-search tool, which separates it from search_graph and other 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?

Provides explicit workflow guidance: 'Use after search_graph when you need the supporting proof behind a trend.' It also states when not to use the tool with 'not a text search tool,' clarifying its role relative to alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context beyond annotations by revealing that label='Trend' returns a 'full deterministic list,' and that search may return partial results. This helps an agent understand completeness behaviors not visible in the schema or 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 purposeful sentences: the first states the core behavior, the second gives an example of the expected question type, and the third provides a targeted non-obvious tip. No content is wasted and the key behavior 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?

With annotations covering safety and idempotency, the description adds enough operational guidance for common usage. It explains graph vs. search behavior and gives actionable examples for parameter selection. It doesn't describe the return format, but because the tool is a straightforward list operation, this is not a major 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 coverage is 100%, so baseline is 3. The description adds value beyond schema by clarifying that label='Trend' yields a complete, deterministic list and by giving concrete examples of graph-content exploration. It does not deeply explain every parameter, but the schema already documents them thoroughly.

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 distinguishes the tool from siblings by contrasting it with search, which 'may return partial results.' This lets an agent immediately identify the tool's scope and function.

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 such as 'what brands are in the retail graph?' and indicates when to prefer this tool for a complete list via label='Trend'. It implicitly routes away from search for full lists, but it does not explicitly name the alternative tool or state hard when-not-to-use conditions.

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 and destructiveHint=false. The description adds meaningful behavioral context beyond annotations by stating 'Returns live data — not cached from session start', which clarifies data freshness. No contradictions 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?

Three concise sentences: first states what the tool does and what it returns, second gives usage examples, third adds a behavioral note. Every sentence earns its place with 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?

For a parameterless, read-only tool with good annotations, the description covers all essential aspects: purpose, usage triggers, behavioral characteristic (live data). No missing elements given the simplicity of the tool.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Per guidelines, baseline is 4 when there are no parameters. The description does not need to add parameter information and correctly focuses on the tool's purpose.

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 the verb 'Check' with a specific resource ('current user's account status'), enumerates exact fields (API call balance, plan, graphs, profile info), and naturally distinguishes from all listed sibling tools which serve different purposes (e.g., get_capabilities, check_supplemental_status).

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 example queries ('how many API calls do I have?', 'what plan am I on?') that clearly indicate when to use this tool. It does not explicitly mention when not to use it or suggest alternatives, but the context is well-defined and sufficient given that sibling tools have clearly distinct purposes.

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, and destructiveHint. The description adds useful behavioral context beyond this on the output is a service of curated editorial connections that a web search cannot provide, and that a prior search_graph call is a prerequisite — which shapes how the agent sequences calls.

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

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

The description is concise and front-loaded with the core purpose in the first sentence, followed by usage guidance. There is a small amount of redundancy between 'search alone wouldn't surface' and 'web search cannot provide', but it is overall effective and not overly wordy.

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 traversal tool, the description adequately sets up expected inputs (node_id from search_graph) and output type (curated editorial connections), and the schema covers parameters in depth. The lack of an output schema and the omission of how to consume results is a minor gap, but the description still provides enough to 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?

Schema description coverage is 100%, so the parameters are already fully documented in the input schema. The description does not add parameter-specific detail beyond the schema, but it reinforces the critical seed_node_ids requirement ('MUST be actual node_id values from a prior search_graph result'), which aligns with the schema's own emphasis.

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 (discover, returns) and resource (connections to a specific trend), and explicitly contrasts with 'search alone wouldn't surface' and 'search_graph'. This clearly distinguishes it from the sibling search_graph tool and conveys that it provides editorial connections.

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

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

The description explicitly says 'Use after search_graph to map the territory around a trend' and explains the kinds of questions it answers (brands, cross-domain relationships). It also states the shared condition ('Requires node_id from a prior search_graph result'). However, it does not explicitly say when not to use this tool or how it compares with siblings like get_node or get_evidence.

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 disclose readOnly, idempotent, non-destructive behavior. The description adds useful context by naming the exact data categories returned (lifecycle stage, signal strength, geographic scope, properties) and emphasizing the dependency on a prior node_id.

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

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

Two sentences are sufficient: the first states purpose and contents, the second states when to use it and the required input. No filler or redundant restating of the tool name.

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

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

For a simple read-only node retrieval tool, the description covers the resource, the expected output contents, the prerequisite input, and the triggering condition. The schema fills in the remaining parameter 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 description coverage is 100%, so the schema already explains graphId, nodeId, and userId. The description reinforces the nodeId provenance rule but does not add material parameter meaning 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 names an exact action and resource: get the full profile of a specific trend. It further distinguishes itself from search_graph by positioning this as a deeper detail on a single node after a summary result.

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 states when to use the tool: 'Use when you need deeper detail on a single trend after search_graph returned a summary.' It also specifies a hard prerequisite: the node_id must come from a prior search_graph result.

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 this as readOnlyHint true and destructiveHint false, and the description adds meaningful behavioral context beyond that: parallel fan-out across 80+ sources, categorized data blocks, source attribution, and metadata in the return. It does not mention latency, rate limits, or how to interpret empty results, but for a read-only open-world data lookup tool the added context is strong.

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 tight and front-loaded: it defines the tool, states when to use it, gives examples, and ends with the behavioral note about search_graph. Every sentence contributes useful information without redeploying or padding.

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 adequately explains the return shape at a high level: categorized data blocks with source attribution and metadata. It is also sufficiently rich on conditions, sources, and call-order guidance. The main gap is that it does not describe possible failure modes, empty results, or how rich the output blocks actually are, but the tool is still reasonably contextual.

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

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

Schema coverage is 100%, so the baseline is 3. The description itself does not add much param-level detail, though it does reinforce that query can be demand/attention-shaped or count/topic-oriented. The schema already covers country hints, brands, domain, and graph IDs thoroughly, so the description is not burdened to fill in param gaps.

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 (supplemental market context) and a specific action (retrieve data from 80+ authoritative sources), and clearly frames when this tool is meant for: thin or empty curated coverage. It also contrasts with the search_graph workflow by explicitly positioning this as the follow-up layer, so an agent can distinguish 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?

The description gives an explicit trigger condition: call it when curated coverage is thin or empty, or when the query is demand/attention-shaped. It also provides concrete examples (search volume, economic series, census data) and names the preceding tool condition ('after search_graph indicates thin/empty coverage'), which gives clear operational guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds context about access control ('the user can access') and details what is returned (IDs, descriptions, authors, sectors, signal counts, topic coverage), going beyond the bare safety profile. It does not mention edge cases like empty results, but the annotations lower the bar.

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

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

The description is two sentences with no filler. The first sentence states the action and output contents; the second gives usage timing and downstream value. Every sentence earns its place and the structure is optimally front-loaded.

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

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

For a simple list tool with no output schema, the description fully covers purpose, usage context, and return metadata. It also clarifies the relationship to other tools via graphId, making it a complete entry point for a session.

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%: the only parameter userId has a clear description. The tool description doesn't add extra parameter-level detail, but it is consistent with 'user can access' and the schema already covers semantics, 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 uses a specific verb 'List' with a clear resource ('expert knowledge graphs') and scope ('the user can access'). It distinguishes itself from sibling tools like search_graph by positioning as a discovery step before searching, with explicit mention of returning graphId parameters for other 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 gives explicit usage timing: 'Use FIRST in any session to discover available sources before searching.' It also explains downstream utility ('needed for graphId parameters in other tools'), making it clear when this tool should be invoked relative to alternatives.

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

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

Annotations already carry the readOnly, openWorld, idempotent, and non-destructive hints, so the description only needed to add behavioral context beyond that. It does so by saying the output is 'clean text' ready for analysis, which is genuinely useful for the agent. It does not mention potential failures on inaccessible URLs, but nothing contradicts 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 concise and front-loaded: verb phrase first, then the trigger use case with concrete examples, then the output format. Every sentence adds value and there is no 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?

The tool has one required parameter, no output schema, and useful annotations. The description explains what input is expected and what kind of result is returned, and the use-case grounding makes the agent's decision easy. It could add caveats about URL availability or authentication, but it is reasonably complete for this 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 description coverage is 100%, with a clear description for both url and userId. The description adds no parameter-specific semantics beyond the schema, but with full coverage it does not need to. A baseline of 3 is appropriate.

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

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

The description begins with a specific verb and resource: 'Extract clean text content from any URL.' It also communicates the tool's niche—ingesting external links—which distinguishes it from graph-focused siblings like get_node and 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 explicitly says when to use the tool: when a user shares a link such as a competitor site, news article, client brief, or trend report and wants to cross-reference it against Fodda knowledge graphs. It does not name exclusions or alternative tools, but the use case is clear enough for an agent to select it confidently.

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

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

The description adds valuable behavioral detail beyond the annotations by disclosing the parallel search-all-graphs default and the enriched output format ('trend data with cited evidence, source attribution, and lifecycle stage'). It does not mention rate limits, pagination, or what happens with invalid graph IDs, but those are not essential for a read-only search tool. Annotations declare readOnly and destructive false; the description is consistent with these, so 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?

The description is four tight sentences, each contributing a distinct, non-redundant piece of information: what it does, what it returns, its default behavior, and when to use it. There is no filler or re-statement of the tool name.

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 9 parameters and no output schema, the description covers the essential context: output structure, default search behavior, and representative use cases. It does not directly mention the 'compare' mode or the effect of skills/semantic parameters, but those are detailed in the schema and do not prevent correct high-level selection. The absence of an output schema is mitigated by the stated return format.

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

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

Schema description coverage is 100%, so every parameter already has a meaningful description. The tool description does not add additional parameter-level insight beyond restating the graphId default, which is already present in the schema. The baseline of 3 applies because the schema carries the full weight of parameter semantics.

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: 'Find trends, signals, and expert insights across 100+ curated knowledge graphs...' and immediately differentiates the tool by stating it returns curated trend data with cited evidence rather than 'generic web summaries'. It also names the covered domains, making the tool's scope unmistakable.

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

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

The description explicitly lists appropriate use cases: 'Use for market trends, competitor analysis, innovation signals, consumer behavior, cultural shifts, or any topic where curated expert intelligence outperforms web search.' It recommends the default behavior of searching all graphs when graphId is omitted, which guides invocation. It does not explicitly name an alternative tool or say 'don't use this when X', but the clear use-case list provides substantive guidance.

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