NetNest Design Fundamentals API

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

With no annotations, the description carries the full behavioral burden and does well by disclosing the data source (SEC filings), covered periods, and per-number provenance including form type, filing date, and SEC link. It still omits operational details such as behavior for invalid tickers, missing filings, permissions, or rate limits.

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 core retrieval scope and then details the returned metrics and provenance. Both sentences are informative 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?

Because there is no output schema, the description appropriately explains the returned financial fields and their accompanying metadata. Completeness is slightly reduced by the absence of edge-case behavior and sibling-tool routing guidance.

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?

There is only one parameter, ticker, and schema description coverage is 100%, so the schema already documents its meaning with an example. The description adds only the phrase 'for one ticker' and does not supplement the schema with format or edge-case 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 names a specific retrieval action and resource: latest company financials from SEC filings for one ticker. It clearly enumerates the metrics and periods returned, so the tool's purpose is easy to understand, but it does not distinguish this tool from the sibling get_fundamentals.

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 says what data is returned but gives no explicit guidance on when to use this tool instead of get_fundamentals, get_history, or search_company. It also does not state exclusions or prerequisites, leaving usage selection to inference.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that values follow each company's fiscal year and that every number carries its source filing, filing date, and accession number — real provenance behavior. However, it says nothing about permissions, rate limits, or failure modes, leaving notable gaps.

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, tightly front-loaded with the returned resource before the period/metric instructions and the fiscal-year caveat. The long metric enumeration is dense but every clause delivers information; minor trimming possible.

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 does the work of explaining return content (metrics plus filing provenance) and the fiscal-calendar nuance, and the schema covers all parameters. Remaining gaps are edge cases (non-fiscal-year tickers, historical requests) rather than essentials.

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 ticker, period, and the metric list. The description restates the metric names and period options rather than adding syntax or format 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 names a concrete resource (latest company fundamentals from SEC filings) and enumerates the exact metrics returned, so an agent knows precisely what this retrieves. It does not explicitly contrast itself with siblings (get_company, get_history, search_company), so it falls short of a 5.

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 only guidance is 'Choose metrics and period (annual, quarterly or ttm)', which tells the agent how to parameterize the call rather than when to prefer this tool over get_history or get_company. Usage is implied by the metric list but no exclusions or alternatives are stated.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: results are ordered newest first, capped at 200 periods, and each period carries its 10-K/10-Q, filing date, and SEC link. It does not cover auth requirements or whether the source data is cached, so it falls short of 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?

Two front-loaded sentences with the core purpose first and the return shape second; no filler. The metric enumeration ('revenue history, net income history, EPS history, cash flow history and more') is mildly redundant with the schema enum but still aids scanning.

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 4-parameter, read-only retrieval tool with no output schema, the description usefully explains what each returned period contains, which the schema cannot convey. Auth/rate behavior is unaddressed, but the description is otherwise sufficient to 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 ticker, metric, period, and limit. The description restates the metric and period options ('by year, quarter or trailing twelve months') without adding syntax, defaults, or edge-case guidance beyond the schema, 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?

States a specific verb and resource: retrieving the financial history of a single metric sourced from SEC filings, with concrete examples (revenue, net income, EPS, cash flow). It clearly reads as a historical-series tool, but never names or contrasts itself against siblings like get_fundamentals, leaving the agent to infer the distinction.

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?

Usage is only implied: 'history ... newest first' suggests a time-series query as opposed to a snapshot. There is no explicit statement of when to prefer this over get_fundamentals or get_company, and no prerequisites or exclusions are given.

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

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

With no annotations at all, the description carries the full behavioral burden. It adds real context the schema cannot supply — data provenance ('Data from SEC filings'), cost ('Free'), and a liability disclaimer — but says nothing about read-only safety, result freshness, matching behavior (exact vs fuzzy), or whether the limit applies per field.

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 short clauses, front-loaded with the core verb and resource, followed by the bidirectionality and the data source. Nothing is padded or redundant; even the disclaimer is a single compact fragment.

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 two-parameter lookup with no output schema and no annotations, the description covers purpose and provenance but leaves the return shape and match behavior unspecified, and it fails to differentiate from the sibling 'get_company'. Adequate but with clear gaps an agent would have to resolve by trial.

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 both parameters ('q' and 'limit') are already fully documented in the schema. The description adds nothing about parameter semantics beyond what is structured — no indication of whether the query is prefix-matched, case-sensitive, or what happens if 'q' is ambiguous. 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?

States a specific verb and resource ('ticker and company name lookup') and clarifies the lookup is bidirectional, so the agent knows it accepts either a name or a ticker. However, it does not distinguish this from the sibling 'get_company', which by name sounds like it may do the same thing.

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?

Usage is only implied through the bidirectional framing ('find the ticker for a company name, or the company for a ticker'), which does hint at the input use case. There is no when-to-use versus when-not-to-use guidance and no mention of the alternatives 'get_company' or 'get_fundamentals'.

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