FirmTape Geo - public records of world events

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

With no annotations, the description carries the transparency burden, and it discloses non-obvious behavior: the current day is excluded from averaging and returned separately, and feeds that turned on inside the window are explicitly flagged. It doesn't describe the response shape or mention read-only/auth behavior, so it isn't 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, front-loaded with the core output then the edge-case behavior. The explanatory clauses ('so a window can be read...', 'because a rise...') are helpful but slightly ornamental, so it earns a 4 rather than a 5.

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?

It covers purpose, usage, and algorithmic edge cases, and the schema covers parameter syntax thoroughly. The main gap is the absence of an output schema combined with no explicit statement of the response structure, which leaves some ambiguity for an agent calling without prior knowledge.

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

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

Schema coverage is 100%, with detailed descriptions for each of the 7 parameters, so the description doesn't need to clarify them. The description's only parameter-related contribution is calling everything a 'filter'; it adds no meaning beyond the schema, which lands exactly at baseline.

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

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

The description clearly identifies a data-analysis activity: per-day record counts for a filter plus a median baseline, and it distinguishes this from plain record listing by emphasizing comparison to a window's own normal. It doesn't explicitly say 'returns' and relies on the schema for filter mechanics, so it stops 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?

It gives a clear intended context: read a time window against its own normal and avoid misreading new feeds as real growth. It does not name sibling alternatives or provide explicit when-not-to-use exclusions, which would be needed for a 5.

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 burden and discloses meaningful behaviors: a record naming multiple countries counts in each, results are sorted most notable first, and it returns counts and last-time info. These details go beyond a simple listing and help an agent interpret output. It doesn't mention side effects, but as a read-only query this is adequately transparent.

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 tight sentences, no redundancy, and the key purpose is front-loaded. Every clause earns its place; the alternate tools are named but not over-explained.

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?

Since there is no output schema, the description explains what the return values will be (countries, record/notable counts, time of last). It names related sibling tools and provides enough context for an agent to use it correctly, though it does not detail effect of each parameter on results—that is covered by the input 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?

Schema describes parameters fully (100% coverage), so baseline is 3. The description adds value by explaining that a record counts in every country it names, which clarifies how the underlying data is aggregated. It also implies 'window' ties to since/until/days, and 'notable' relates to min_severity, enriching semantic understanding 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 clearly states the tool lists countries with counts and the time of the last record, sorted by notability. It specifies the precise resource (countries in the archive) and differentiates itself from siblings like geo_snapshot and geo_records by positioning itself as the country-selection step.

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

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

Explicitly instructs to use this tool to pick a country before calling geo_snapshot or geo_records instead of guessing. This provides a clear when-to-use directive and names the alternatives, leaving no ambiguity about the tool's role in the workflow.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly explains that backfill rows are counted apart, that rows where publication_time_is_ours is true have zero lag by construction, and that the metric reflects collection speed rather than news-market speed. These are substantive edge cases and interpretation caveats, not just restatements of the schema.

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 opening sentence immediately states the core purpose, and later sentences each add meaningful behavioral context. It is somewhat long, but every sentence earns its place with caveats that materially affect interpretation.

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 parameters, no annotations, and no output schema, the description is remarkably complete. It explains the metric units, the grouping by feed, the backfill behavior, the special zero-lag case, and a market-speed caveat, giving an agent everything needed to interpret results 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%, so baseline 3 applies. The description adds contextual framing about the 90-day window and per-feed grouping, but it does not elaborate on parameter syntax or formats beyond what the schema already documents.

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 measurement task: how long after a source published a record it reached us, with median, 90th percentile, and worst case in seconds per feed. This clearly distinguishes it from siblings like geo_records or geo_sources, which focus on records or source metadata.

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 its use case from the task definition, and it gives useful context about backfill counting and the publication_time_is_ours caveat. However, it never explicitly names alternative tools or explains when not to use it, leaving the routing to inference rather than clear 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?

With no annotations, the description carries the burden of behavioral disclosure. It states ordering ('newest first'), time range ('up to a year back'), timezone ('all UTC'), and record contents (source, link, publication time, first-seen time). It also discloses that uid is for exact records. It does not mention pagination limits or rate limits, but the schema covers cursor/limit; the key behavioral traits are disclosed.

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: three sentences. It front-loads the core purpose ('records themselves, newest first'), then lists categories and record fields, then routes to siblings. No fluff; every sentence earns its place.

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

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

For a 10-parameter tool with no output schema and no annotations, the description covers the essential context: record types, ordering, time window, fields, and sibling relationships. It does not spell out the exact response JSON, but it enumerates the record fields, which is sufficient. Pagination is implied by the schema (cursor), and severity semantics are in the schema. Overall, it is nearly complete, missing only explicit response format details.

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

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

Schema coverage is 100%, so every parameter already has a description. The description adds minimal parameter-specific meaning—only reinforcing uid usage ('Ask for one exact record with uid') and the existence of a 'q' for title words is not expanded. Baseline 3 is appropriate since the schema does the heavy lifting and the description does not go beyond it.

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

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

The description clearly states it returns 'records themselves' and enumerates the types of records (advisories, sanctions, flight restrictions, etc.), establishing a specific resource. It also distinguishes itself from geo_activity (counts) and geo_snapshot (one country), so an agent can immediately tell it apart 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 provides when-not guidance: 'For how many rather than which, call geo_activity; for one country in one call, geo_snapshot.' It also adds an interpretive caveat ('Context, never a trading signal') helping the agent know how to use results. This is clear, actionable routing.

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 discloses the structure of each series (recent points, normal, ratio, normal_ready), explains when normal_ready is false (baseline too short), and explains the ratio_note condition (normal too small to divide by). It even adds operational context (AIS collectors hourly, chokepoints passing 2-3 ships a day). This is thorough disclosure of edge cases and logic, beyond what annotations would provide.

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

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

The description is long but densely packed with essential information. It front-loads the core purpose ('measured series for one country') and then expands with a list of series types and data structure. Every clause contributes value (e.g., the ratio_note condition is explained). No fluff exists, though it could be trimmed slightly, the detail is justified by the tool's complexity.

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

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

Given no output schema, the description adequately explains what the tool returns: the series types and the per-series fields. It also covers edge cases (normal_ready, ratio_note) and operational context. An agent can confidently invoke this tool and interpret results without ambiguity. Missing details like authentication are irrelevant for a read-only data retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it clarifies that 'id' comes from a previous answer (implying a chaining workflow) and reinforces country as ISO alpha-2. This is useful context that helps the agent understand how to populate parameters, exceeding the baseline.

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

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

The description clearly states the resource ('the measured series for one country') and enumerates the specific series types (aircraft overhead, military aircraft, ships, IPv4 space, etc.), making the tool's function unmistakable. However, it does not explicitly differentiate from sibling tools like geo_activity or geo_snapshot; the differentiation is implicit through the term 'series' and the list of contents. This is strong but lacks a direct sibling 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?

The description implies usage: an agent needing time-series data for a country with baselines and ratios would select this tool. It does not provide explicit 'when to use' vs 'when not to use' guidance, nor name alternatives. The context of siblings exists but is not addressed. Thus, usage context is implied rather than spelled out.

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 transparency burden. It explicitly says the operation is 'counted, not written', and it defines boundaries by excluding 'narrative, score and forecast'. It does not disclose the output structure, how 'notable' is determined, or cross-section pagination, but it reveals the key read-only and scope characteristics.

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

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

Two sentences with no filler. The core aggregation and scope are front-loaded in the first sentence, and the exclusions and read-only nature are delivered in the second. Every clause earns its place.

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

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

For a tool with no output schema and no annotations, the description gives a clear inventory of the returned content areas and explicitly states what the call does not produce. Combined with 100% schema parameter coverage, an agent has enough to select and invoke it, though the exact meaning of 'notable records' and 'against its own normal' is left implicit.

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 the conceptual context of one country and aggregated sections, but it does not explain how days, limit, since, or until interact with the three result groups beyond 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 opening 'One country in one call' plus the enumeration 'record counts by sector and by feed, its notable records, and every measured series' states a specific consolidated listing resource. It also names the sibling origin tools (geo_records, geo_activity, geo_series), making it clearly distinguishable as a single-country aggregate rather than a general 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 explicitly frames the tool as 'geo_records, geo_activity and geo_series for a single country', so an agent can infer it is the right choice when a consolidated per-country snapshot is needed. It does not give explicit when-not conditions or name an alternative for multi-country or analytical needs, but the usage context is clear.

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

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

No annotations are present, so the description must disclose behavioral traits on its own. It explains the conceptual meaning of feed failure (a quiet window may indicate a stopped feed), but it does not explicitly state read-only guarantees, side effects, auth/rate limits, or how fresh the 'last answered' data is. The provided context is useful but not a full behavioral disclosure.

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, each earning its place: the first lists the returned fields, the second explains why the tool should be used, and the third redirects to a sibling. The middle sentence is slightly metaphorical but carries meaningful guidance, and the structure front-loads the core 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 zero-parameter read tool with no output schema, the description covers the returned data fields, the use case, and the key alternative. It does not explain interpretation of fields like failure streak or record count, but an agent has enough to call the tool correctly. Minor gaps remain but are not critical.

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 are zero parameters, and the schema confirms an empty object. Per the rubric, 0 params earns a baseline of 4; the description adds no parameter-specific detail because none is needed.

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 exactly what the tool provides: feed metadata (id, sector, last-answer time, failure streak, record count). It is clearly distinct from geo_latency by naming the specific alternative, and it does not conflate with other siblings like geo_records or geo_coverage.

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

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

Explicitly instructs when to use this tool ('Read this before trusting a quiet window') and gives the condition that should route the agent to geo_latency ('For how late each feed's records arrive'). This is direct, actionable guidance with no inference required.

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